1 /* 2 * Copyright 2018 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 androidx.work; 18 19 import android.support.annotation.NonNull; 20 import android.support.annotation.WorkerThread; 21 22 import java.util.List; 23 import java.util.UUID; 24 import java.util.concurrent.TimeUnit; 25 26 /** 27 * Blocking methods for {@link WorkManager} operations. These methods are expected to be called 28 * from a background thread. 29 */ 30 public interface SynchronousWorkManager { 31 32 /** 33 * Enqueues one or more {@link WorkRequest} in a synchronous fashion. This method is expected to 34 * be called from a background thread and, upon successful execution, you can rely on that the 35 * work has been enqueued. 36 * 37 * @param workRequest The Array of {@link WorkRequest} 38 */ 39 @WorkerThread 40 void enqueueSync(@NonNull WorkRequest... workRequest); 41 42 /** 43 * Enqueues the List of {@link WorkRequest} in a synchronous fashion. This method is expected to 44 * be called from a background thread and, upon successful execution, you can rely on that the 45 * work has been enqueued. 46 * 47 * @param workRequest The List of {@link WorkRequest} 48 */ 49 @WorkerThread 50 void enqueueSync(@NonNull List<? extends WorkRequest> workRequest); 51 52 /** 53 * This method allows you to synchronously enqueue a uniquely-named {@link PeriodicWorkRequest}, 54 * where only one PeriodicWorkRequest of a particular name can be active at a time. For 55 * example, you may only want one sync operation to be active. If there is one pending, you can 56 * choose to let it run or replace it with your new work. 57 * 58 * This method is expected to be called from a background thread. 59 * 60 * The {@code uniqueWorkName} uniquely identifies this PeriodicWorkRequest. 61 * 62 * @param uniqueWorkName A unique name which for this operation 63 * @param existingPeriodicWorkPolicy An {@link ExistingPeriodicWorkPolicy} 64 * @param periodicWork A {@link PeriodicWorkRequest} to enqueue. {@code REPLACE} ensures that if 65 * there is pending work labelled with {@code uniqueWorkName}, it will be 66 * cancelled and the new work will run. {@code KEEP} will run the new 67 * PeriodicWorkRequest only if there is no pending work labelled with 68 * {@code uniqueWorkName}. 69 */ 70 @WorkerThread 71 void enqueueUniquePeriodicWorkSync( 72 @NonNull String uniqueWorkName, 73 @NonNull ExistingPeriodicWorkPolicy existingPeriodicWorkPolicy, 74 @NonNull PeriodicWorkRequest periodicWork); 75 76 /** 77 * Cancels work with the given id in a synchronous fashion if it isn't finished. Note that 78 * cancellation is dependent on timing (for example, the work could have completed in a 79 * different thread just as you issue this call). Use {@link #getStatusByIdSync(UUID)} to 80 * find out the actual state of the work after this call. This method is expected to be called 81 * from a background thread. 82 * 83 * @param id The id of the work 84 */ 85 @WorkerThread 86 void cancelWorkByIdSync(@NonNull UUID id); 87 88 /** 89 * Cancels all unfinished work with the given tag in a synchronous fashion. Note that 90 * cancellation is dependent on timing (for example, the work could have completed in a 91 * different thread just as you issue this call). Use {@link #getStatusByIdSync(UUID)} to 92 * find out the actual state of the work after this call. This method is expected to be called 93 * from a background thread. 94 * 95 * @param tag The tag used to identify the work 96 */ 97 @WorkerThread 98 void cancelAllWorkByTagSync(@NonNull String tag); 99 100 /** 101 * Cancels all unfinished work in the work chain with the given name in a synchronous fashion. 102 * Note that cancellation is dependent on timing (for example, the work could have completed in 103 * a different thread just as you issue this call). Use {@link #getStatusByIdSync(UUID)} to 104 * find out the actual state of the work after this call. This method is expected to be called 105 * from a background thread. 106 * 107 * @param uniqueWorkName The unique name used to identify the chain of work 108 */ 109 @WorkerThread 110 void cancelUniqueWorkSync(@NonNull String uniqueWorkName); 111 112 /** 113 * Cancels all unfinished work in a synchronous fashion. <b>Use this method with extreme 114 * caution!</b> By invoking it, you will potentially affect other modules or libraries in your 115 * codebase. It is strongly recommended that you use one of the other cancellation methods at 116 * your disposal. 117 */ 118 @WorkerThread 119 void cancelAllWorkSync(); 120 121 /** 122 * Gets the timestamp of the last time all work was cancelled in a synchronous fashion. This 123 * method is intended for use by library and module developers who have dependent data in their 124 * own repository that must be updated or deleted in case someone cancels their work without 125 * their prior knowledge. 126 * 127 * @return The timestamp in milliseconds when a method that cancelled all work was last invoked 128 */ 129 @WorkerThread 130 long getLastCancelAllTimeMillisSync(); 131 132 /** 133 * Prunes all eligible finished work from the internal database in a synchronous fashion. 134 * Eligible work must be finished ({@link State#SUCCEEDED}, {@link State#FAILED}, or 135 * {@link State#CANCELLED}), with zero unfinished dependents. 136 * <p> 137 * <b>Use this method with caution</b>; by invoking it, you (and any modules and libraries in 138 * your codebase) will no longer be able to observe the {@link WorkStatus} of the pruned work. 139 * You do not normally need to call this method - WorkManager takes care to auto-prune its work 140 * after a sane period of time. This method also ignores the 141 * {@link OneTimeWorkRequest.Builder#keepResultsForAtLeast(long, TimeUnit)} policy. 142 */ 143 @WorkerThread 144 void pruneWorkSync(); 145 146 /** 147 * Gets the {@link WorkStatus} of a given work id in a synchronous fashion. This method is 148 * expected to be called from a background thread. 149 * 150 * @param id The id of the work 151 * @return A {@link WorkStatus} associated with {@code id} 152 */ 153 @WorkerThread 154 WorkStatus getStatusByIdSync(@NonNull UUID id); 155 156 /** 157 * Gets the {@link WorkStatus} for all work with a given tag in a synchronous fashion. This 158 * method is expected to be called from a background thread. 159 * 160 * @param tag The tag of the work 161 * @return A list of {@link WorkStatus} for work tagged with {@code tag} 162 */ 163 @WorkerThread 164 List<WorkStatus> getStatusesByTagSync(@NonNull String tag); 165 166 /** 167 * Gets the {@link WorkStatus} for all work for the chain of work with a given unique name in a 168 * synchronous fashion. This method is expected to be called from a background thread. 169 * 170 * @param uniqueWorkName The unique name used to identify the chain of work 171 * @return A list of {@link WorkStatus} for work in the chain named {@code uniqueWorkName} 172 */ 173 @WorkerThread 174 List<WorkStatus> getStatusesForUniqueWorkSync(@NonNull String uniqueWorkName); 175 } 176
