1 package com.android.onboarding.tasks 2 3 import com.google.common.util.concurrent.ListenableFuture 4 import java.util.concurrent.ConcurrentHashMap 5 6 /** 7 * Manages the execution and state of onboarding tasks within the onboarding process. This interface 8 * provides a set of functions for triggering a task, monitoring, and obtaining results from 9 * onboarding tasks. 10 */ 11 interface OnboardingTaskManager { 12 13 /** 14 * Executes an onboarding task asynchronously and returns a token for subsequent status queries. 15 * 16 * @param taskContract The contract defining the task's arguments and result for the onboarding 17 * task. 18 * @return The token associated with the initiated onboarding task. 19 */ runTasknull20 fun <TaskResultT, TaskContractT : OnboardingTaskContract<Unit, TaskResultT>> runTask( 21 taskContract: TaskContractT 22 ): OnboardingTaskToken = runTask(taskContract, Unit) 23 24 /** 25 * Executes an onboarding task asynchronously and returns a token for subsequent status queries. 26 * 27 * @param taskContract The contract defining task's arguments and result for the onboarding task. 28 * @param taskArgs A defined argument for the onboarding task. 29 * @return The token associated with the initiated onboarding task. 30 */ 31 fun < 32 TaskArgsT, 33 TaskResultT, 34 TaskContractT : OnboardingTaskContract<TaskArgsT, TaskResultT>, 35 > runTask(taskContract: TaskContractT, taskArgs: TaskArgsT): OnboardingTaskToken 36 37 /** 38 * Executes an onboarding task asynchronously and waits for its completion, providing the final 39 * result. 40 * 41 * @param taskContract The contract defining task's arguments and result for the onboarding task. 42 * @param taskArgs A defined argument for the onboarding task. 43 * @return The final result of the onboarding task. 44 */ 45 suspend fun < 46 TaskArgsT, 47 TaskResultT, 48 TaskContractT : OnboardingTaskContract<TaskArgsT, TaskResultT>, 49 > runTaskAndGetResult( 50 taskContract: TaskContractT, 51 taskArgs: TaskArgsT, 52 ): OnboardingTaskState<TaskResultT> 53 54 /** 55 * Executes an onboarding task asynchronously and waits for its completion, providing the final 56 * result. 57 * 58 * @param taskContract The contract defining task's arguments and result for the onboarding task. 59 * @param task The onboarding task to be executed. 60 * @param taskArgs A defined argument for the onboarding task. 61 * @return The final result of the onboarding task. 62 */ 63 @Deprecated("Use new overload function - runTaskAndGetResult().") 64 suspend fun < 65 TaskArgsT, 66 TaskResultT, 67 TaskContractT : OnboardingTaskContract<TaskArgsT, TaskResultT>, 68 > runTaskAndGetResult( 69 taskContract: TaskContractT, 70 task: OnboardingTask<TaskArgsT, TaskResultT, TaskContractT>, 71 taskArgs: TaskArgsT, 72 ): OnboardingTaskState<TaskResultT> 73 74 /** 75 * Executes an onboarding task asynchronously and waits for its completion, providing the final 76 * result. 77 * 78 * @param taskContract The contract defining task's arguments and result for the onboarding task. 79 * @param taskArgs A defined argument for the onboarding task. 80 * @return A [ListenableFuture] representing the final state of the onboarding task. The future 81 * encapsulates the asynchronous execution and completion of the task, allowing for the 82 * retrieval of the task state or result. 83 */ 84 fun < 85 TaskArgsT, 86 TaskResultT, 87 TaskContractT : OnboardingTaskContract<TaskArgsT, TaskResultT>, 88 > runTaskAndGetResultAsync( 89 taskContract: TaskContractT, 90 taskArgs: TaskArgsT, 91 ): ListenableFuture<OnboardingTaskState<TaskResultT>> 92 93 /** 94 * Executes an onboarding task asynchronously and waits for its completion, providing the final 95 * result. 96 * 97 * @param taskContract The contract defining task's arguments and result for the onboarding task. 98 * @param task The onboarding task to be executed. 99 * @param taskArgs A defined argument for the onboarding task. 100 * @return A [ListenableFuture] representing the final state of the onboarding task. The future 101 * encapsulates the asynchronous execution and completion of the task, allowing for the 102 * retrieval of the task state or result. 103 */ 104 @Deprecated("Use new overload function - runTaskAndGetResultAsync().") 105 fun < 106 TaskArgsT, 107 TaskResultT, 108 TaskContractT : OnboardingTaskContract<TaskArgsT, TaskResultT>, 109 > runTaskAndGetResultAsync( 110 taskContract: TaskContractT, 111 task: OnboardingTask<TaskArgsT, TaskResultT, TaskContractT>, 112 taskArgs: TaskArgsT, 113 ): ListenableFuture<OnboardingTaskState<TaskResultT>> 114 115 /** 116 * Retrieves the current state of a previously initiated onboarding task. 117 * 118 * @param taskToken The token associated with the onboarding task. 119 * @return The result of the onboarding task. 120 */ 121 fun <TaskResultT> getTaskState(taskToken: OnboardingTaskToken): OnboardingTaskState<TaskResultT> 122 123 /** 124 * Waits for the result of a previously initiated onboarding task. 125 * 126 * If the provided [taskToken] is not valid, the caller receives a null object, indicating that 127 * this token is not recorded in the manager. 128 * 129 * If the [taskToken] represents a task in a timeout state or encounters an exeception, the caller 130 * receives a [OnboardingTaskState.Failed] state. 131 * 132 * If the onboarding task completes successfully, the caller receives a 133 * [OnboardingTaskState.Completed] state with [Result] data. 134 * 135 * @param taskToken The token associated with the onboarding task. 136 * @return The final result of the onboarding task. 137 */ 138 suspend fun <TaskResultT> waitForCompleted( 139 taskToken: OnboardingTaskToken 140 ): OnboardingTaskState<TaskResultT> 141 142 /** 143 * Asynchronously waits for the result of a previously initiated onboarding task. 144 * 145 * If the provided [taskToken] is not valid, the caller receives a null object, indicating that 146 * this token is not recorded in the manager. 147 * 148 * If the [taskToken] represents a task in a timeout state or encounters an exeception, the caller 149 * receives a [OnboardingTaskState.Failed] state. 150 * 151 * If the onboarding task completes successfully, the caller receives a 152 * [OnboardingTaskState.Completed] state with [Result] data. 153 * 154 * @param taskToken The token associated with the onboarding task. 155 * @return A [ListenableFuture] containing the final result of the onboarding task. 156 */ 157 fun <TaskResultT> waitForCompletedAsync( 158 taskToken: OnboardingTaskToken 159 ): ListenableFuture<OnboardingTaskState<TaskResultT>> 160 161 fun getContractAndTaskMap(): 162 ConcurrentHashMap<Class<out OnboardingTaskContract<*, *>>, Class<out OnboardingTask<*, *, *>>> 163 } 164