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 package androidx.work
17 
18 /**
19  * An enumeration of the conflict resolution policies available to unique [PeriodicWorkRequest]s in
20  * case of a collision.
21  */
22 enum class ExistingPeriodicWorkPolicy {
23     /**
24      * If there is existing pending (uncompleted) work with the same unique name, cancel and delete
25      * it. Then, insert the newly-specified work.
26      */
27     @Deprecated(
28         message =
29             "Deprecated in favor of the UPDATE policy. UPDATE policy has " +
30                 "very similar behavior: next run of the worker with the same unique name, " +
31                 "going to have new specification. However, UPDATE has better defaults: " +
32                 "unlike REPLACE policy UPDATE won't cancel the worker if it is currently running and " +
33                 "new worker specification will be used only on the next run. " +
34                 "Also it preserves original enqueue time, so unlike REPLACE period isn't reset. " +
35                 "If you want to preserve previous behavior, CANCEL_AND_REENQUEUE should be used.",
36         replaceWith = ReplaceWith("UPDATE"),
37     )
38     REPLACE,
39 
40     /**
41      * If there is existing pending (uncompleted) work with the same unique name, do nothing.
42      * Otherwise, insert the newly-specified work.
43      */
44     KEEP,
45 
46     /**
47      * If there is existing pending (uncompleted) work with the same unique name, it will be updated
48      * with the new specification. Otherwise, new work with the given name will be enqueued.
49      *
50      * It preserves enqueue time, e.g. if a work was run 3 hours ago and had 8 hours long period,
51      * after the update it would be still eligible for run in 5 hours, assuming that periodicity
52      * wasn't updated.
53      *
54      * If the work being updated is currently running, the current run won't be interrupted and will
55      * continue to rely on previous state of the request, e.g. using old constraints, tags etc.
56      * However, on the next iteration of periodic worker, the new worker specification will be used.
57      *
58      * If the work was previously cancelled (via [WorkManager.cancelWorkById] or similar), it will
59      * be deleted and then the newly-specified work will be enqueued.
60      */
61     UPDATE,
62 
63     /**
64      * If there is existing pending (uncompleted) work with the same unique name, cancel and delete
65      * it. Then, insert the newly-specified work.
66      *
67      * It is identical for `REPLACE`. But for readability reasons it is better to use
68      * `CANCEL_AND_REENQUEUE`, because for a reader the difference between `REPLACE` vs `UPDATED` is
69      * unclear.
70      */
71     CANCEL_AND_REENQUEUE,
72 }
73