Worker.java revision 188b6fb0e5da3723f28c23289b5b55086210e82c 
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
17package androidx.work;
18
19import android.content.Context;
20import android.support.annotation.NonNull;
21import android.support.annotation.WorkerThread;
22
23/**
24 * The basic unit of work.
25 */
26public abstract class Worker {
27
28    public enum WorkerResult {
29        SUCCESS,
30        FAILURE,
31        RETRY
32    }
33
34    private Context mAppContext;
35    private @NonNull String mId;
36    private @NonNull Arguments mArguments;
37    private Arguments mOutput;
38
39    public final Context getAppContext() {
40        return mAppContext;
41    }
42
43    public final @NonNull String getId() {
44        return mId;
45    }
46
47    public final @NonNull Arguments getArguments() {
48        return mArguments;
49    }
50
51    /**
52     * Override this method to do your actual background processing.
53     *
54     * @return The result of the work, corresponding to a {@link WorkerResult} value.  If a
55     * different value is returned, the result shall be defaulted to
56     * {@link Worker.WorkerResult#FAILURE}.
57     */
58    @WorkerThread
59    public abstract WorkerResult doWork();
60
61    /**
62     * Call this method to pass an {@link Arguments} object to {@link Work} that is dependent on
63     * this one.  Note that if there are multiple {@link Worker}s that contribute to the target, the
64     * Arguments will be merged together, so it is up to the developer to make sure that keys are
65     * unique.  New values and types will clobber old values and types, and if there are multiple
66     * parent Workers of a child Worker, the order of clobbering may not be deterministic.
67     *
68     * This method is invoked after {@link #doWork()} returns {@link Worker.WorkerResult#SUCCESS}
69     * and there are chained jobs available.
70     *
71     * For example, if you had this structure:
72     *
73     * {@code WorkManager.getInstance()
74     *            .enqueueWithDefaults(WorkerA.class, WorkerB.class)
75     *            .then(WorkerC.class)
76     *            .enqueue()}
77     *
78     * This method would be called for both WorkerA and WorkerB after their successful completion,
79     * modifying the input Arguments for WorkerC.
80     *
81     * @param output An {@link Arguments} object that will be merged into the input Arguments of any
82     *               Work that is dependent on this one, or {@code null} if there is nothing to
83     *               contribute
84     */
85    public final void setOutput(Arguments output) {
86        mOutput = output;
87    }
88
89    public final Arguments getOutput() {
90        return mOutput;
91    }
92
93    private void internalInit(
94            Context appContext,
95            @NonNull String id,
96            @NonNull Arguments arguments) {
97        mAppContext = appContext;
98        mId = id;
99        mArguments = arguments;
100    }
101
102    /**
103     * Determines if the {@link Worker} was interrupted and should stop executing.
104     * The {@link Worker} can be interrupted for the following reasons:
105     * 1. The {@link Work} or {@link PeriodicWork} was explicitly cancelled.
106     *    {@link WorkManager#cancelAllWorkWithTag(String)}
107     * 2. Constraints set in {@link Work} or {@link PeriodicWork} are no longer valid.
108     * @return {@code true} if {@link Worker} is instructed to stop executing.
109     */
110    protected final boolean isInterrupted() {
111        return Thread.currentThread().isInterrupted();
112    }
113}
114