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 import android.os.Build
19 import androidx.annotation.NonNull
20 import kotlin.reflect.KClass
21 
22 /**
23  * A [WorkRequest] for non-repeating work.
24  *
25  * OneTimeWorkRequests can be put in simple or complex graphs of work by using methods like
26  * [WorkManager.enqueue] or [WorkManager.beginWith].
27  */
28 class OneTimeWorkRequest internal constructor(builder: Builder) :
29     WorkRequest(builder.id, builder.workSpec, builder.tags) {
30     /**
31      * Builder for [OneTimeWorkRequest]s.
32      *
33      * @param workerClass The [ListenableWorker] class to run for this work
34      */
35     class Builder(workerClass: Class<out ListenableWorker>) :
36         WorkRequest.Builder<Builder, OneTimeWorkRequest>(workerClass) {
37 
38         /**
39          * Creates a builder for [OneTimeWorkRequest]s.
40          *
41          * @param workerClass The [ListenableWorker] class to run for this work
42          */
43         constructor(workerClass: KClass<out ListenableWorker>) : this(workerClass.java)
44 
45         /**
46          * Specifies the [InputMerger] class name for this [OneTimeWorkRequest].
47          *
48          * Before workers run, they receive input [Data] from their parent workers, as well as
49          * anything specified directly to them via [WorkRequest.Builder.setInputData]. An
50          * InputMerger takes all of these objects and converts them to a single merged [Data] to be
51          * used as the worker input. The default InputMerger is [OverwritingInputMerger]. This
52          * library also offers [ArrayCreatingInputMerger]; you can also specify your own.
53          *
54          * @param inputMerger The class name of the [InputMerger] for this [OneTimeWorkRequest]
55          * @return The current [Builder]
56          */
setInputMergernull57         fun setInputMerger(inputMerger: Class<out InputMerger>): Builder {
58             workSpec.inputMergerClassName = inputMerger.name
59             return this
60         }
61 
buildInternalnull62         override fun buildInternal(): OneTimeWorkRequest {
63             require(
64                 !(backoffCriteriaSet &&
65                     Build.VERSION.SDK_INT >= 23 &&
66                     workSpec.constraints.requiresDeviceIdle())
67             ) {
68                 "Cannot set backoff criteria on an idle mode job"
69             }
70             return OneTimeWorkRequest(this)
71         }
72 
73         override val thisObject: Builder
74             get() = this
75     }
76 
77     companion object {
78         /**
79          * Creates a [OneTimeWorkRequest] with defaults from a [ListenableWorker] class name.
80          *
81          * @param workerClass An [ListenableWorker] class name
82          * @return A [OneTimeWorkRequest] constructed by using defaults in the [Builder]
83          */
84         @JvmStatic
fromnull85         fun from(workerClass: Class<out ListenableWorker>): OneTimeWorkRequest {
86             return Builder(workerClass).build()
87         }
88 
89         /**
90          * Creates a list of [OneTimeWorkRequest]s with defaults from an array of [ListenableWorker]
91          * class names.
92          *
93          * @param workerClasses A list of [ListenableWorker] class names
94          * @return A list of [OneTimeWorkRequest] constructed by using defaults in the [ ]
95          */
96         @JvmStatic
fromnull97         fun from(workerClasses: List<Class<out ListenableWorker>>): List<OneTimeWorkRequest> {
98             return workerClasses.map { Builder(it).build() }
99         }
100     }
101 }
102 
103 /** Creates a [OneTimeWorkRequest] with the given [ListenableWorker]. */
OneTimeWorkRequestBuildernull104 public inline fun <reified W : ListenableWorker> OneTimeWorkRequestBuilder():
105     OneTimeWorkRequest.Builder = OneTimeWorkRequest.Builder(W::class.java)
106 
107 /** Sets an [InputMerger] on the [OneTimeWorkRequest.Builder]. */
108 @Suppress("NOTHING_TO_INLINE")
109 public inline fun OneTimeWorkRequest.Builder.setInputMerger(
110     @NonNull inputMerger: KClass<out InputMerger>
111 ): OneTimeWorkRequest.Builder = setInputMerger(inputMerger.java)
112