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.arch.lifecycle.LiveData; 19 import android.support.annotation.NonNull; 20 import android.support.annotation.Nullable; 21 import android.support.annotation.RestrictTo; 22 23 import java.util.Arrays; 24 import java.util.List; 25 26 /** 27 * An opaque class that allows you to chain together {@link OneTimeWorkRequest}. 28 */ 29 public abstract class WorkContinuation { 30 31 /** 32 * Adds new {@link OneTimeWorkRequest} items that depend on the successful completion of 33 * all previously added {@link OneTimeWorkRequest}. 34 * 35 * @param work One or more {@link OneTimeWorkRequest} to add to the {@link WorkContinuation} 36 * @return A {@link WorkContinuation} that allows for further chaining of dependent 37 * {@link OneTimeWorkRequest} 38 */ then(@onNull OneTimeWorkRequest... work)39 public final WorkContinuation then(@NonNull OneTimeWorkRequest... work) { 40 return then(Arrays.asList(work)); 41 } 42 43 /** 44 * Adds new {@link OneTimeWorkRequest} items that depend on the successful completion 45 * of all previously added {@link OneTimeWorkRequest}. 46 * 47 * @param work One or more {@link OneTimeWorkRequest} to add to the {@link WorkContinuation} 48 * @return A {@link WorkContinuation} that allows for further chaining of dependent 49 * {@link OneTimeWorkRequest} 50 */ then(@onNull List<OneTimeWorkRequest> work)51 public abstract WorkContinuation then(@NonNull List<OneTimeWorkRequest> work); 52 53 /** 54 * Returns a {@link LiveData} list of {@link WorkStatus} that provides information about work, 55 * their progress, and any resulting output. If state or outputs of any of the jobs in this 56 * chain changes, any attached {@link android.arch.lifecycle.Observer}s will trigger. 57 * 58 * @return A {@link LiveData} containing a list of {@link WorkStatus}es 59 */ getStatuses()60 public abstract LiveData<List<WorkStatus>> getStatuses(); 61 62 /** 63 * Enqueues the instance of {@link WorkContinuation} on the background thread. 64 */ enqueue()65 public abstract void enqueue(); 66 67 /** 68 * Gets an object that gives access to synchronous methods. 69 * 70 * @return A {@link SynchronousWorkContinuation} object, which gives access to synchronous 71 * methods 72 */ synchronous()73 public abstract SynchronousWorkContinuation synchronous(); 74 75 /** 76 * Combines multiple {@link WorkContinuation}s to allow for complex chaining. 77 * 78 * @param continuations Two or more {@link WorkContinuation}s that are prerequisites for the 79 * return value 80 * @return A {@link WorkContinuation} that allows further chaining 81 */ combine(@onNull WorkContinuation... continuations)82 public static WorkContinuation combine(@NonNull WorkContinuation... continuations) { 83 return combine(Arrays.asList(continuations)); 84 } 85 86 /** 87 * Combines multiple {@link WorkContinuation}s to allow for complex chaining. 88 * 89 * @param continuations Two or more {@link WorkContinuation}s that are prerequisites for the 90 * return value 91 * @return A {@link WorkContinuation} that allows further chaining 92 */ combine(@onNull List<WorkContinuation> continuations)93 public static WorkContinuation combine(@NonNull List<WorkContinuation> continuations) { 94 if (continuations.size() < 2) { 95 throw new IllegalArgumentException( 96 "WorkContinuation.combine() needs at least 2 continuations."); 97 } 98 99 return continuations.get(0).combineInternal(null, continuations); 100 } 101 102 /** 103 * Combines multiple {@link WorkContinuation}s to allow for complex chaining using the 104 * {@link OneTimeWorkRequest} provided. 105 * 106 * @param work The {@link OneTimeWorkRequest} which depends on the successful completion of the 107 * provided {@link WorkContinuation}s 108 * @param continuations Two or more {@link WorkContinuation}s that are prerequisites for the 109 * {@link OneTimeWorkRequest} provided. 110 * @return A {@link WorkContinuation} that allows further chaining 111 */ combine( @onNull OneTimeWorkRequest work, @NonNull WorkContinuation... continuations)112 public static WorkContinuation combine( 113 @NonNull OneTimeWorkRequest work, 114 @NonNull WorkContinuation... continuations) { 115 return combine(work, Arrays.asList(continuations)); 116 } 117 118 /** 119 * Combines multiple {@link WorkContinuation}s to allow for complex chaining using the 120 * {@link OneTimeWorkRequest} provided. 121 * 122 * @param work The {@link OneTimeWorkRequest} which depends on the successful completion of the 123 * provided {@link WorkContinuation}s 124 * @param continuations Two or more {@link WorkContinuation}s that are prerequisites for the 125 * {@link OneTimeWorkRequest} provided. 126 * @return A {@link WorkContinuation} that allows further chaining 127 */ combine( @onNull OneTimeWorkRequest work, @NonNull List<WorkContinuation> continuations)128 public static WorkContinuation combine( 129 @NonNull OneTimeWorkRequest work, 130 @NonNull List<WorkContinuation> continuations) { 131 return continuations.get(0).combineInternal(work, continuations); 132 } 133 134 /** 135 * @hide 136 */ 137 @RestrictTo(RestrictTo.Scope.LIBRARY_GROUP) combineInternal( @ullable OneTimeWorkRequest work, @NonNull List<WorkContinuation> continuations)138 protected abstract WorkContinuation combineInternal( 139 @Nullable OneTimeWorkRequest work, 140 @NonNull List<WorkContinuation> continuations); 141 } 142