1 /* 2 * Copyright (C) 2016 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.phone.vvm.omtp.scheduling; 18 19 import android.annotation.MainThread; 20 import android.annotation.WorkerThread; 21 import android.content.Context; 22 import android.content.Intent; 23 import java.util.Objects; 24 25 /** 26 * A task for {@link TaskSchedulerService} to execute. Since the task is sent through a intent to 27 * the scheduler, The task must be constructable with the intent. Specifically, It must have a 28 * constructor with zero arguments, and have all relevant data packed inside the intent. Use {@link 29 * TaskSchedulerService#createIntent(Context, Class)} to create a intent that will construct the 30 * Task. 31 * 32 * <p>Only {@link #onExecuteInBackgroundThread()} is run on the worker thread. 33 */ 34 public interface Task { 35 36 /** 37 * TaskId to indicate it has not be set. If a task does not provide a default TaskId it should 38 * be set before {@link Task#onCreate(Context, Intent, int, int) returns} 39 */ 40 int TASK_INVALID = -1; 41 42 /** 43 * TaskId to indicate it should always be queued regardless of duplicates. {@link 44 * Task#onDuplicatedTaskAdded(Task)} will never be called on tasks with this TaskId. 45 */ 46 int TASK_ALLOW_DUPLICATES = -2; 47 48 int TASK_UPLOAD = 1; 49 int TASK_SYNC = 2; 50 int TASK_ACTIVATION = 3; 51 52 /** 53 * Used to differentiate between types of tasks. If a task with the same TaskId is already in 54 * the queue the new task will be rejected. 55 */ 56 class TaskId { 57 58 /** 59 * Indicates the operation type of the task. 60 */ 61 public final int id; 62 /** 63 * Same operation for a different subId is allowed. subId is used to differentiate phone 64 * accounts in multi-SIM scenario. For example, each SIM can queue a sync task for their 65 * own. 66 */ 67 public final int subId; 68 TaskId(int id, int subId)69 public TaskId(int id, int subId) { 70 this.id = id; 71 this.subId = subId; 72 } 73 74 @Override equals(Object object)75 public boolean equals(Object object) { 76 if (!(object instanceof TaskId)) { 77 return false; 78 } 79 TaskId other = (TaskId) object; 80 return id == other.id && subId == other.subId; 81 } 82 83 @Override hashCode()84 public int hashCode() { 85 return Objects.hash(id, subId); 86 } 87 } 88 getId()89 TaskId getId(); 90 91 @MainThread onCreate(Context context, Intent intent, int flags, int startId)92 void onCreate(Context context, Intent intent, int flags, int startId); 93 94 /** 95 * @return number of milliSeconds the scheduler should wait before running this task. A value 96 * less than {@link TaskSchedulerService#READY_TOLERANCE_MILLISECONDS} will be considered ready. 97 * If no tasks are ready, the scheduler will sleep for this amount of time before doing another 98 * check (it will still wake if a new task is added). The first task in the queue that is ready 99 * will be executed. 100 */ 101 @MainThread getReadyInMilliSeconds()102 long getReadyInMilliSeconds(); 103 104 /** 105 * Called on the main thread when the scheduler is about to send the task into the worker 106 * thread, calling {@link #onExecuteInBackgroundThread()} 107 */ 108 @MainThread onBeforeExecute()109 void onBeforeExecute(); 110 111 /** 112 * The actual payload of the task, executed on the worker thread. 113 */ 114 @WorkerThread onExecuteInBackgroundThread()115 void onExecuteInBackgroundThread(); 116 117 /** 118 * Called on the main thread when {@link #onExecuteInBackgroundThread()} has finished or thrown 119 * an uncaught exception. The task is already removed from the queue at this point, and a same 120 * task can be queued again. 121 */ 122 @MainThread onCompleted()123 void onCompleted(); 124 125 /** 126 * Another task with the same TaskId has been added. Necessary data can be retrieved from the 127 * other task, and after this returns the task will be discarded. 128 */ 129 @MainThread onDuplicatedTaskAdded(Task task)130 void onDuplicatedTaskAdded(Task task); 131 } 132