OLD | NEW |
---|---|
(Empty) | |
1 // Copyright 2017 The Chromium Authors. All rights reserved. | |
2 // Use of this source code is governed by a BSD-style license that can be | |
3 // found in the LICENSE file. | |
4 | |
5 package org.chromium.components.background_task_scheduler; | |
6 | |
7 import android.content.Context; | |
8 import android.os.Bundle; | |
9 import android.support.annotation.IntDef; | |
10 import android.support.annotation.NonNull; | |
11 | |
12 import java.lang.annotation.Retention; | |
13 import java.lang.annotation.RetentionPolicy; | |
14 | |
15 /** | |
16 * TaskInfo represents a request to run a specific {@link BackgroundTask} given the required | |
17 * parameters, such as whether a special type of network is available. | |
18 */ | |
19 public class TaskInfo { | |
20 /** | |
21 * Specifies information regarding one-off tasks. | |
22 * This is part of a {@link TaskInfo} iff the task is NOT a periodic task. | |
23 */ | |
24 public static class OneOffInfo { | |
25 private final long mWindowStartTimeMs; | |
26 private final long mWindowEndTimeMs; | |
27 private final boolean mHasWindowStartTimeConstraint; | |
28 | |
29 private OneOffInfo(long windowStartTimeMs, long windowEndTimeMs, | |
30 boolean hasWindowStartTimeConstraint) { | |
31 mWindowStartTimeMs = windowStartTimeMs; | |
32 mWindowEndTimeMs = windowEndTimeMs; | |
33 mHasWindowStartTimeConstraint = hasWindowStartTimeConstraint; | |
34 } | |
35 | |
36 /** | |
37 * @return the start of the window that the task can begin executing as a delta in | |
38 * milliseconds from now. | |
39 */ | |
40 public long getWindowStartTimeMs() { | |
41 return mWindowStartTimeMs; | |
42 } | |
43 | |
44 /** | |
45 * @return the end of the window that the task can begin executing as a delta in | |
46 * milliseconds from now. | |
47 */ | |
48 public long getWindowEndTimeMs() { | |
49 return mWindowEndTimeMs; | |
50 } | |
51 | |
52 /** | |
53 * @return whether this one-off task has a window start time constraint. | |
54 */ | |
55 public boolean hasWindowStartTimeConstraint() { | |
56 return mHasWindowStartTimeConstraint; | |
57 } | |
58 | |
59 @Override | |
60 public String toString() { | |
61 return "{windowStartTimeMs: " + mWindowStartTimeMs + ", windowEndTim eMs: " | |
62 + mWindowEndTimeMs + "}"; | |
63 } | |
64 } | |
65 | |
66 /** | |
67 * Specifies information regarding periodic tasks. | |
68 * This is part of a {@link TaskInfo} iff the task is a periodic task. | |
69 */ | |
70 public static class PeriodicInfo { | |
71 private final long mIntervalMs; | |
72 private final long mFlexMs; | |
73 private final boolean mHasFlex; | |
74 | |
75 private PeriodicInfo(long intervalMs, long flexMs, boolean hasFlex) { | |
76 mIntervalMs = intervalMs; | |
77 mFlexMs = flexMs; | |
78 mHasFlex = hasFlex; | |
79 } | |
80 | |
81 /** | |
82 * @return the interval between occurrences of this task in milliseconds . | |
83 */ | |
84 public long getIntervalMs() { | |
85 return mIntervalMs; | |
86 } | |
87 | |
88 /** | |
89 * @return the flex time for this task. The task can execute at any time in a window of flex | |
90 * length at the end of the period. It is reported in milliseconds. | |
91 */ | |
92 public long getFlexMs() { | |
93 return mFlexMs; | |
94 } | |
95 | |
96 /** | |
97 * @return true whether this task has defined a flex time. False otherwi se. | |
98 */ | |
99 public boolean hasFlex() { | |
100 return mHasFlex; | |
101 } | |
102 | |
103 @Override | |
104 public String toString() { | |
105 StringBuilder sb = new StringBuilder("{"); | |
106 sb.append("{"); | |
107 sb.append("intervalMs: ").append(mIntervalMs); | |
108 if (mHasFlex) { | |
109 sb.append(", flexMs: ").append(mFlexMs); | |
110 } | |
111 sb.append("}"); | |
112 return sb.toString(); | |
113 } | |
114 } | |
115 | |
116 @Retention(RetentionPolicy.SOURCE) | |
117 @IntDef({NETWORK_TYPE_NONE, NETWORK_TYPE_ANY, NETWORK_TYPE_UNMETERED}) | |
118 public @interface NetworkType {} | |
119 | |
120 /** | |
121 * This task has no requirements for network connectivity. Default. | |
122 * @see NetworkType | |
123 */ | |
124 public static final int NETWORK_TYPE_NONE = 0; | |
125 /** | |
126 * This task requires network connectivity. | |
127 * @see NetworkType | |
128 */ | |
129 public static final int NETWORK_TYPE_ANY = 1; | |
130 /** | |
131 * This task requires network connectivity that is unmetered. | |
132 * @see NetworkType | |
133 */ | |
134 public static final int NETWORK_TYPE_UNMETERED = 2; | |
135 | |
136 /** | |
137 * The task ID should be unique across all tasks. A list of such unique IDs exists in | |
138 * {@link TaskIds}. | |
139 */ | |
140 private final int mTaskId; | |
141 | |
142 /** | |
143 * The {@link BackgroundTask} to invoke when this task is run. | |
144 */ | |
145 @NonNull | |
146 private final Class<? extends BackgroundTask> mBackgroundTaskClass; | |
147 | |
148 /** | |
149 * The extras to provide to the {@link BackgroundTask} when it is run. | |
150 */ | |
151 @NonNull | |
152 private final Bundle mExtras; | |
153 | |
154 /** | |
155 * The type of network the task requires to run. | |
156 */ | |
157 @NetworkType | |
158 private final int mRequiredNetworkType; | |
159 | |
160 /** | |
161 * Whether the task requires charging to run. | |
162 */ | |
163 private final boolean mRequiresCharging; | |
164 | |
165 /** | |
166 * Whether or not to persist this task across device reboots. | |
167 */ | |
168 private final boolean mIsPersisted; | |
169 | |
170 /** | |
171 * Whether this task should override any preexisting tasks with the same tas k id. | |
172 */ | |
173 private final boolean mUpdateCurrent; | |
174 | |
175 /** | |
176 * Whether this task is periodic. | |
177 */ | |
178 private final boolean mIsPeriodic; | |
179 | |
180 /** | |
181 * Task information regarding one-off tasks. Non-null iff {@link #mIsPeriodi c} is false. | |
182 */ | |
183 private final OneOffInfo mOneOffInfo; | |
184 | |
185 /** | |
186 * Task information regarding periodic tasks. Non-null iff {@link #mIsPeriod ic} is true. | |
187 */ | |
188 private final PeriodicInfo mPeriodicInfo; | |
189 | |
190 private TaskInfo(Builder builder) { | |
191 mTaskId = builder.mTaskId; | |
192 mBackgroundTaskClass = builder.mBackgroundTaskClass; | |
193 mExtras = builder.mExtras == null ? new Bundle() : builder.mExtras; | |
194 mRequiredNetworkType = builder.mRequiredNetworkType; | |
195 mRequiresCharging = builder.mRequiresCharging; | |
196 mIsPersisted = builder.mIsPersisted; | |
197 mUpdateCurrent = builder.mUpdateCurrent; | |
198 mIsPeriodic = builder.mIsPeriodic; | |
199 if (mIsPeriodic) { | |
200 mOneOffInfo = null; | |
201 mPeriodicInfo = | |
202 new PeriodicInfo(builder.mIntervalMs, builder.mFlexMs, build er.mHasFlex); | |
203 } else { | |
204 mOneOffInfo = new OneOffInfo(builder.mWindowStartTimeMs, builder.mWi ndowEndTimeMs, | |
205 builder.mHasWindowStartTimeConstraint); | |
206 mPeriodicInfo = null; | |
207 } | |
208 } | |
209 | |
210 /** | |
211 * @return the unique ID of this task. | |
212 */ | |
213 public int getTaskId() { | |
214 return mTaskId; | |
215 } | |
216 | |
217 /** | |
218 * @return the {@link BackgroundTask} class that will be instantiated for th is task. | |
219 */ | |
220 @NonNull | |
221 public Class<? extends BackgroundTask> getBackgroundTaskClass() { | |
222 return mBackgroundTaskClass; | |
223 } | |
224 | |
225 /** | |
226 * @return the extras that will be provided to the {@link BackgroundTask}. | |
227 */ | |
228 @NonNull | |
229 public Bundle getExtras() { | |
230 return mExtras; | |
231 } | |
232 | |
233 /** | |
234 * @return the type of network the task requires to run. | |
235 */ | |
236 @NetworkType | |
237 public int getRequiredNetworkType() { | |
238 return mRequiredNetworkType; | |
239 } | |
240 | |
241 /** | |
242 * @return whether the task requires charging to run. | |
243 */ | |
244 public boolean requiresCharging() { | |
245 return mRequiresCharging; | |
246 } | |
247 | |
248 /** | |
249 * @return whether or not to persist this task across device reboots. | |
250 */ | |
251 public boolean isPersisted() { | |
252 return mIsPersisted; | |
253 } | |
254 | |
255 /** | |
256 * @return whether this task should override any preexisting tasks with the same task id. | |
257 */ | |
258 public boolean shouldUpdateCurrent() { | |
259 return mUpdateCurrent; | |
260 } | |
261 | |
262 /** | |
263 * @return Whether or not this task is a periodic task. | |
264 */ | |
265 public boolean isPeriodic() { | |
266 return mIsPeriodic; | |
267 } | |
268 | |
269 /** | |
270 * This is part of a {@link TaskInfo} iff the task is NOT a periodic task, i. e. | |
271 * {@link TaskInfo#isPeriodic()} returns false. | |
272 * @return the specific data that is only available for one-off tasks. | |
273 */ | |
274 public OneOffInfo getOneOffInfo() { | |
275 return mOneOffInfo; | |
276 } | |
277 | |
278 /** | |
279 * This is part of a {@link TaskInfo} iff the task is a periodic task, i.e. | |
280 * {@link TaskInfo#isPeriodic()} returns true. | |
281 * @return the specific data that is only available for periodic tasks. | |
282 */ | |
283 public PeriodicInfo getPeriodicInfo() { | |
284 return mPeriodicInfo; | |
285 } | |
286 | |
287 @Override | |
288 public String toString() { | |
289 StringBuilder sb = new StringBuilder(); | |
290 sb.append("{"); | |
291 sb.append("taskId: ").append(mTaskId); | |
292 sb.append(", backgroundTaskClass: ").append(mBackgroundTaskClass); | |
293 sb.append(", extras: ").append(mExtras); | |
294 sb.append(", requiredNetworkType: ").append(mRequiredNetworkType); | |
295 sb.append(", requiresCharging: ").append(mRequiresCharging); | |
296 sb.append(", isPersisted: ").append(mIsPersisted); | |
297 sb.append(", updateCurrent: ").append(mUpdateCurrent); | |
298 sb.append(", isPeriodic: ").append(mIsPeriodic); | |
299 if (isPeriodic()) { | |
300 sb.append(", periodicInfo: ").append(mPeriodicInfo); | |
301 } else { | |
302 sb.append(", oneOffInfo: ").append(mOneOffInfo); | |
303 } | |
304 sb.append("}"); | |
305 return sb.toString(); | |
306 } | |
307 | |
308 /** | |
309 * Schedule a one-off task to execute within a deadline. If windowEndTimeMs is 0, the task will | |
310 * run as soon as possible. For executing a task within a time window, see | |
311 * {@link #createOneOffTask(int, Class, long, long)}. | |
312 * @param taskId the unique task ID for this task. Should be listed in {@lin k TaskIds}. | |
313 * @param backgroundTaskClass the {@link BackgroundTask} class that will be instantiated for | |
314 * this task. | |
315 * @param windowEndTimeMs the end of the window that the task can begin exec uting as a delta in | |
316 * milliseconds from now. | |
317 * @return the builder which can be used to continue configuration and {@lin k Builder#build()}. | |
318 * @see TaskIds | |
319 */ | |
320 public static Builder createOneOffTask( | |
321 int taskId, Class<? extends BackgroundTask> backgroundTaskClass, lon g windowEndTimeMs) { | |
322 return new Builder(taskId, backgroundTaskClass, false).setWindowEndTimeM s(windowEndTimeMs); | |
323 } | |
324 | |
325 /** | |
326 * Schedule a one-off task to execute within a time window. For executing a task within a | |
327 * deadline, see {@link #createOneOffTask(int, Class, long)}, | |
328 * @param taskId the unique task ID for this task. Should be listed in {@lin k TaskIds}. | |
329 * @param backgroundTaskClass the {@link BackgroundTask} class that will be instantiated for | |
330 * this task. | |
331 * @param windowStartTimeMs the start of the window that the task can begin executing as a delta | |
332 * in | |
333 * milliseconds from now. | |
Peter Beverloo
2017/02/24 18:07:12
micro nit: weird wrapping
nyquist
2017/02/24 23:41:12
Wow, yeah. That was weird. Done.
| |
334 * @param windowEndTimeMs the end of the window that the task can begin exec uting as a delta in | |
335 * milliseconds from now. | |
336 * @return the builder which can be used to continue configuration and {@lin k Builder#build()}. | |
337 * @see TaskIds | |
338 */ | |
339 public static Builder createOneOffTask(int taskId, | |
340 Class<? extends BackgroundTask> backgroundTaskClass, long windowStar tTimeMs, | |
341 long windowEndTimeMs) { | |
342 return new Builder(taskId, backgroundTaskClass, false) | |
343 .setWindowStartTimeMs(windowStartTimeMs) | |
344 .setWindowEndTimeMs(windowEndTimeMs); | |
345 } | |
346 | |
347 /** | |
348 * Schedule a periodic task that will recur at the specified interval, witho ut the need to | |
349 * be rescheduled. The task will continue to recur until | |
350 * {@link BackgroundTaskScheduler#cancel(Context, int)} is invoked with the task ID from this | |
351 * {@link TaskInfo}. | |
352 * @param taskId the unique task ID for this task. Should be listed in {@lin k TaskIds}. | |
353 * @param backgroundTaskClass the {@link BackgroundTask} class that will be instantiated for | |
354 * this task. | |
355 * @param intervalMs the interval between occurrences of this task in millis econds. | |
356 * @return the builder which can be used to continue configuration and {@lin k Builder#build()}. | |
357 * @see TaskIds | |
358 */ | |
359 public static Builder createPeriodicTask( | |
360 int taskId, Class<? extends BackgroundTask> backgroundTaskClass, lon g intervalMs) { | |
361 return new Builder(taskId, backgroundTaskClass, true).setIntervalMs(inte rvalMs); | |
362 } | |
363 | |
364 /** | |
365 * Schedule a periodic task that will recur at the specified interval, witho ut the need to | |
366 * be rescheduled. The task will continue to recur until | |
367 * {@link BackgroundTaskScheduler#cancel(Context, int)} is invoked with the task ID from this | |
368 * {@link TaskInfo}. | |
369 * The flex time specifies how close to the end of the interval you are will ing to execute. | |
370 * Instead of executing at the exact interval, the task will execute at the interval or up to | |
371 * flex milliseconds before. | |
372 * @param taskId the unique task ID for this task. Should be listed in {@lin k TaskIds}. | |
373 * @param backgroundTaskClass the {@link BackgroundTask} class that will be instantiated for | |
374 * this task. | |
375 * @param intervalMs the interval between occurrences of this task in millis econds. | |
376 * @param flexMs the flex time for this task. The task can execute at any ti me in a window of | |
377 * flex | |
378 * length at the end of the period. It is reported in milliseconds. | |
379 * @return the builder which can be used to continue configuration and {@lin k Builder#build()}. | |
380 * @see TaskIds | |
381 */ | |
382 public static Builder createPeriodicTask(int taskId, | |
383 Class<? extends BackgroundTask> backgroundTaskClass, long intervalMs , long flexMs) { | |
384 return new Builder(taskId, backgroundTaskClass, true) | |
385 .setIntervalAndFlexMs(intervalMs, flexMs); | |
386 } | |
387 | |
388 /** | |
389 * A helper builder to provide a way to build {@link TaskInfo}. To create a {@link Builder} | |
390 * use one of the create* class method on {@link TaskInfo}. | |
391 * | |
392 * @see #createOneOffTask(int, Class, long) | |
393 * @see #createOneOffTask(int, Class, long, long) | |
394 * @see #createPeriodicTask(int, Class, long) | |
395 * @see #createPeriodicTask(int, Class, long, long) | |
396 */ | |
397 public static final class Builder { | |
398 private final int mTaskId; | |
399 @NonNull | |
400 private final Class<? extends BackgroundTask> mBackgroundTaskClass; | |
401 private final boolean mIsPeriodic; | |
402 private Bundle mExtras; | |
403 @NetworkType | |
404 private int mRequiredNetworkType; | |
405 private boolean mRequiresCharging; | |
406 private boolean mIsPersisted; | |
407 private boolean mUpdateCurrent; | |
408 | |
409 // Data about one-off tasks. | |
410 private long mWindowStartTimeMs; | |
411 private long mWindowEndTimeMs; | |
412 private boolean mHasWindowStartTimeConstraint; | |
413 | |
414 // Data about periodic tasks. | |
415 private long mIntervalMs; | |
416 private long mFlexMs; | |
417 private boolean mHasFlex; | |
418 | |
419 Builder(int taskId, @NonNull Class<? extends BackgroundTask> backgroundT askClass, | |
420 boolean isPeriodic) { | |
421 mTaskId = taskId; | |
422 mBackgroundTaskClass = backgroundTaskClass; | |
423 mIsPeriodic = isPeriodic; | |
424 } | |
425 | |
426 Builder setWindowStartTimeMs(long windowStartTimeMs) { | |
427 assert !mIsPeriodic; | |
428 mWindowStartTimeMs = windowStartTimeMs; | |
429 mHasWindowStartTimeConstraint = true; | |
430 return this; | |
431 } | |
432 | |
433 Builder setWindowEndTimeMs(long windowEndTimeMs) { | |
434 assert !mIsPeriodic; | |
435 mWindowEndTimeMs = windowEndTimeMs; | |
436 return this; | |
437 } | |
438 | |
439 Builder setIntervalMs(long intervalMs) { | |
440 assert mIsPeriodic; | |
441 mIntervalMs = intervalMs; | |
442 return this; | |
443 } | |
444 | |
445 Builder setIntervalAndFlexMs(long intervalMs, long flexMs) { | |
446 assert mIsPeriodic; | |
447 mIntervalMs = intervalMs; | |
448 mFlexMs = flexMs; | |
449 mHasFlex = true; | |
450 return this; | |
451 } | |
452 | |
453 /** | |
454 * Set the optional extra values necessary for this task. Must only ever contain simple | |
455 * values supported by {@link android.os.BaseBundle}. All other values a re thrown away. | |
456 * If the extras for this builder are not set, or set to null, the resul ting | |
457 * {@link TaskInfo} will have an empty bundle (i.e. not null). | |
458 * @param bundle the bundle of extra values necessary for this task. | |
459 * @return this {@link Builder}. | |
460 */ | |
461 public Builder setExtras(Bundle bundle) { | |
462 mExtras = bundle; | |
463 return this; | |
464 } | |
465 | |
466 /** | |
467 * Set the type of network the task requires to run. | |
468 * @param networkType the {@link NetworkType} required for this task. | |
469 * @return this {@link Builder}. | |
470 */ | |
471 public Builder setRequiredNetworkType(@NetworkType int networkType) { | |
472 mRequiredNetworkType = networkType; | |
473 return this; | |
474 } | |
475 | |
476 /** | |
477 * Set whether the task requires charging to run. | |
478 * @param requiresCharging true if this task requires charging. | |
479 * @return this {@link Builder}. | |
480 */ | |
481 public Builder setRequiresCharging(boolean requiresCharging) { | |
482 mRequiresCharging = requiresCharging; | |
483 return this; | |
484 } | |
485 | |
486 /** | |
487 * Set whether or not to persist this task across device reboots. | |
488 * @param isPersisted true if this task should be persisted across reboo ts. | |
489 * @return this {@link Builder}. | |
490 */ | |
491 public Builder setIsPersisted(boolean isPersisted) { | |
492 mIsPersisted = isPersisted; | |
493 return this; | |
494 } | |
495 | |
496 /** | |
497 * Set whether this task should override any preexisting tasks with the same task id. | |
498 * @param updateCurrent true if this task should overwrite a currently e xisting task with | |
499 * the same ID, if it exists. | |
500 * @return this {@link Builder}. | |
501 */ | |
502 public Builder setUpdateCurrent(boolean updateCurrent) { | |
503 mUpdateCurrent = updateCurrent; | |
504 return this; | |
505 } | |
506 | |
507 /** | |
508 * Build the {@link TaskInfo object} specified by this builder. | |
509 * @return the {@link TaskInfo} object. | |
510 */ | |
511 public TaskInfo build() { | |
512 return new TaskInfo(this); | |
513 } | |
514 } | |
515 } | |
OLD | NEW |