1 /* 2 * Copyright 2022 Google LLC 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 package com.google.android.libraries.mobiledatadownload; 17 18 import com.google.auto.value.AutoValue; 19 import com.google.common.base.Optional; 20 21 /** Interface for task scheduling */ 22 public interface TaskScheduler { 23 24 /** 25 * Tag for daily mdd maintenance task, that *should* be run once and only once every 24 hours. 26 * 27 * <p>By default, this task runs on charging. 28 */ 29 String MAINTENANCE_PERIODIC_TASK = "MDD.MAINTENANCE.PERIODIC.GCM.TASK"; 30 31 /** 32 * Tag for mdd task that doesn't require any network. This is used to perform some routine 33 * operation that do not require network, in case a device doesn't connect to any network for a 34 * long time. 35 * 36 * <p>By default, this task runs on charging once every 6 hours. 37 */ 38 String CHARGING_PERIODIC_TASK = "MDD.CHARGING.PERIODIC.TASK"; 39 40 /** 41 * Tag for mdd task that runs on cellular network. This is used to primarily download file groups 42 * that can be download on cellular network. 43 * 44 * <p>By default, this task runs on charging once every 6 hours. This task can be skipped if 45 * nothing is downloaded on cellular. 46 */ 47 String CELLULAR_CHARGING_PERIODIC_TASK = "MDD.CELLULAR.CHARGING.PERIODIC.TASK"; 48 49 /** 50 * Tag for mdd task that runs on wifi network. This is used to primarily download file groups that 51 * can be download only on wifi network. 52 * 53 * <p>By default, this task runs on charging once every 6 hours. This task can be skipped if 54 * nothing is restricted to wifi. 55 */ 56 String WIFI_CHARGING_PERIODIC_TASK = "MDD.WIFI.CHARGING.PERIODIC.TASK"; 57 58 /** Required network state of the device when to run the task. */ 59 enum NetworkState { 60 // Metered or unmetered network available. 61 NETWORK_STATE_CONNECTED, 62 63 // Unmetered network available. 64 NETWORK_STATE_UNMETERED, 65 66 // Network not required. 67 NETWORK_STATE_ANY, 68 } 69 70 /** ConstraintOverrides to allow clients to override background task constraints. */ 71 @AutoValue 72 abstract class ConstraintOverrides { ConstraintOverrides()73 ConstraintOverrides() {} 74 requiresDeviceIdle()75 public abstract boolean requiresDeviceIdle(); 76 requiresCharging()77 public abstract boolean requiresCharging(); 78 requiresBatteryNotLow()79 public abstract boolean requiresBatteryNotLow(); 80 newBuilder()81 public static Builder newBuilder() { 82 // Setting default values. 83 return new AutoValue_TaskScheduler_ConstraintOverrides.Builder() 84 .setRequiresDeviceIdle(true) 85 .setRequiresCharging(true) 86 .setRequiresBatteryNotLow(false); 87 } 88 89 /** Builder for {@link ConstraintOverrides}. */ 90 @AutoValue.Builder 91 public abstract static class Builder { 92 Builder()93 Builder() {} 94 95 /** 96 * Sets whether device should be idle for the MDD task to run. The default value is {@code 97 * true}. 98 * 99 * @param requiresDeviceIdle {@code true} if device must be idle for the work to run 100 */ setRequiresDeviceIdle(boolean requiresDeviceIdle)101 public abstract Builder setRequiresDeviceIdle(boolean requiresDeviceIdle); 102 103 /** 104 * Sets whether device should be charging for the MDD task to run. The default value is {@code 105 * true}. 106 * 107 * @param requiresCharging {@code true} if device must be charging for the work to run 108 */ setRequiresCharging(boolean requiresCharging)109 public abstract Builder setRequiresCharging(boolean requiresCharging); 110 111 /** 112 * Sets whether device battery should be at an acceptable level for the MDD task to run. The 113 * default value is {@code false}. 114 * 115 * @param requiresBatteryNotLow {@code true} if the battery should be at an acceptable level 116 * for the work to run 117 */ setRequiresBatteryNotLow(boolean requiresBatteryNotLow)118 public abstract Builder setRequiresBatteryNotLow(boolean requiresBatteryNotLow); 119 build()120 public abstract ConstraintOverrides build(); 121 } 122 } 123 124 /** 125 * Schedule a periodic using one of GCM, FJD or Work Manager. If you need to override idle and/or 126 * charging requirements, call the method that takes in the constraintOverrides instead. 127 * 128 * @param tag tag of the scheduled task. 129 * @param period period with which the scheduled task should be run. 130 * @param networkState network state when to run the task. 131 */ schedulePeriodicTask(String tag, long period, NetworkState networkState)132 void schedulePeriodicTask(String tag, long period, NetworkState networkState); 133 134 /** 135 * Schedule a periodic using Work Manager. 136 * 137 * @param tag tag of the scheduled task. 138 * @param period period with which the scheduled task should be run. 139 * @param networkState network state when to run the task. 140 * @param constraintOverrides allow overriding the charging and idle requirements. 141 */ schedulePeriodicTask( String tag, long period, NetworkState networkState, Optional<ConstraintOverrides> constraintOverrides)142 default void schedulePeriodicTask( 143 String tag, 144 long period, 145 NetworkState networkState, 146 Optional<ConstraintOverrides> constraintOverrides) { 147 // Default implementation will not override any constraints. Without this, we will have to 148 // update all clients. 149 schedulePeriodicTask(tag, period, networkState); 150 } 151 152 /** 153 * Cancel future invocations of a previously-scheduled task. No guarantee is made whether the task 154 * will be interrupted if it's currently running. 155 * 156 * @param tag tag of the scheduled task. 157 */ cancelPeriodicTask(String tag)158 default void cancelPeriodicTask(String tag) { 159 // TODO(b/223822302): remove default once all implementations have been updated to include it 160 } 161 } 162