Home | History | Annotate | Download | only in work 
      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      */
     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      */
     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      */
     60     public abstract LiveData<List<WorkStatus>> getStatuses();
     61 
     62     /**
     63      * Enqueues the instance of {@link WorkContinuation} on the background thread.
     64      */
     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      */
     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      */
     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      */
     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      */
    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      */
    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)
    138     protected abstract WorkContinuation combineInternal(
    139             @Nullable OneTimeWorkRequest work,
    140             @NonNull List<WorkContinuation> continuations);
    141 }
    142