1/*
2 * Copyright (C) 2014 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 android.app.job;
18
19import android.app.Service;
20import android.content.Intent;
21import android.os.Handler;
22import android.os.IBinder;
23import android.os.Looper;
24import android.os.Message;
25import android.os.RemoteException;
26import android.util.Log;
27
28import com.android.internal.annotations.GuardedBy;
29
30/**
31 * <p>Entry point for the callback from the {@link android.app.job.JobScheduler}.</p>
32 * <p>This is the base class that handles asynchronous requests that were previously scheduled. You
33 * are responsible for overriding {@link JobService#onStartJob(JobParameters)}, which is where
34 * you will implement your job logic.</p>
35 * <p>This service executes each incoming job on a {@link android.os.Handler} running on your
36 * application's main thread. This means that you <b>must</b> offload your execution logic to
37 * another thread/handler/{@link android.os.AsyncTask} of your choosing. Not doing so will result
38 * in blocking any future callbacks from the JobManager - specifically
39 * {@link #onStopJob(android.app.job.JobParameters)}, which is meant to inform you that the
40 * scheduling requirements are no longer being met.</p>
41 */
42public abstract class JobService extends Service {
43    private static final String TAG = "JobService";
44
45    /**
46     * Job services must be protected with this permission:
47     *
48     * <pre class="prettyprint">
49     *     <service android:name="MyJobService"
50     *              android:permission="android.permission.BIND_JOB_SERVICE" >
51     *         ...
52     *     </service>
53     * </pre>
54     *
55     * <p>If a job service is declared in the manifest but not protected with this
56     * permission, that service will be ignored by the OS.
57     */
58    public static final String PERMISSION_BIND =
59            "android.permission.BIND_JOB_SERVICE";
60
61    /**
62     * Identifier for a message that will result in a call to
63     * {@link #onStartJob(android.app.job.JobParameters)}.
64     */
65    private final int MSG_EXECUTE_JOB = 0;
66    /**
67     * Message that will result in a call to {@link #onStopJob(android.app.job.JobParameters)}.
68     */
69    private final int MSG_STOP_JOB = 1;
70    /**
71     * Message that the client has completed execution of this job.
72     */
73    private final int MSG_JOB_FINISHED = 2;
74
75    /** Lock object for {@link #mHandler}. */
76    private final Object mHandlerLock = new Object();
77
78    /**
79     * Handler we post jobs to. Responsible for calling into the client logic, and handling the
80     * callback to the system.
81     */
82    @GuardedBy("mHandlerLock")
83    JobHandler mHandler;
84
85    /** Binder for this service. */
86    IJobService mBinder = new IJobService.Stub() {
87        @Override
88        public void startJob(JobParameters jobParams) {
89            ensureHandler();
90            Message m = Message.obtain(mHandler, MSG_EXECUTE_JOB, jobParams);
91            m.sendToTarget();
92        }
93        @Override
94        public void stopJob(JobParameters jobParams) {
95            ensureHandler();
96            Message m = Message.obtain(mHandler, MSG_STOP_JOB, jobParams);
97            m.sendToTarget();
98        }
99    };
100
101    /** @hide */
102    void ensureHandler() {
103        synchronized (mHandlerLock) {
104            if (mHandler == null) {
105                mHandler = new JobHandler(getMainLooper());
106            }
107        }
108    }
109
110    /**
111     * Runs on application's main thread - callbacks are meant to offboard work to some other
112     * (app-specified) mechanism.
113     * @hide
114     */
115    class JobHandler extends Handler {
116        JobHandler(Looper looper) {
117            super(looper);
118        }
119
120        @Override
121        public void handleMessage(Message msg) {
122            final JobParameters params = (JobParameters) msg.obj;
123            switch (msg.what) {
124                case MSG_EXECUTE_JOB:
125                    try {
126                        boolean workOngoing = JobService.this.onStartJob(params);
127                        ackStartMessage(params, workOngoing);
128                    } catch (Exception e) {
129                        Log.e(TAG, "Error while executing job: " + params.getJobId());
130                        throw new RuntimeException(e);
131                    }
132                    break;
133                case MSG_STOP_JOB:
134                    try {
135                        boolean ret = JobService.this.onStopJob(params);
136                        ackStopMessage(params, ret);
137                    } catch (Exception e) {
138                        Log.e(TAG, "Application unable to handle onStopJob.", e);
139                        throw new RuntimeException(e);
140                    }
141                    break;
142                case MSG_JOB_FINISHED:
143                    final boolean needsReschedule = (msg.arg2 == 1);
144                    IJobCallback callback = params.getCallback();
145                    if (callback != null) {
146                        try {
147                            callback.jobFinished(params.getJobId(), needsReschedule);
148                        } catch (RemoteException e) {
149                            Log.e(TAG, "Error reporting job finish to system: binder has gone" +
150                                    "away.");
151                        }
152                    } else {
153                        Log.e(TAG, "finishJob() called for a nonexistent job id.");
154                    }
155                    break;
156                default:
157                    Log.e(TAG, "Unrecognised message received.");
158                    break;
159            }
160        }
161
162        private void ackStartMessage(JobParameters params, boolean workOngoing) {
163            final IJobCallback callback = params.getCallback();
164            final int jobId = params.getJobId();
165            if (callback != null) {
166                try {
167                     callback.acknowledgeStartMessage(jobId, workOngoing);
168                } catch(RemoteException e) {
169                    Log.e(TAG, "System unreachable for starting job.");
170                }
171            } else {
172                if (Log.isLoggable(TAG, Log.DEBUG)) {
173                    Log.d(TAG, "Attempting to ack a job that has already been processed.");
174                }
175            }
176        }
177
178        private void ackStopMessage(JobParameters params, boolean reschedule) {
179            final IJobCallback callback = params.getCallback();
180            final int jobId = params.getJobId();
181            if (callback != null) {
182                try {
183                    callback.acknowledgeStopMessage(jobId, reschedule);
184                } catch(RemoteException e) {
185                    Log.e(TAG, "System unreachable for stopping job.");
186                }
187            } else {
188                if (Log.isLoggable(TAG, Log.DEBUG)) {
189                    Log.d(TAG, "Attempting to ack a job that has already been processed.");
190                }
191            }
192        }
193    }
194
195    /** @hide */
196    public final IBinder onBind(Intent intent) {
197        return mBinder.asBinder();
198    }
199
200    /**
201     * Override this method with the callback logic for your job. Any such logic needs to be
202     * performed on a separate thread, as this function is executed on your application's main
203     * thread.
204     *
205     * @param params Parameters specifying info about this job, including the extras bundle you
206     *               optionally provided at job-creation time.
207     * @return True if your service needs to process the work (on a separate thread). False if
208     * there's no more work to be done for this job.
209     */
210    public abstract boolean onStartJob(JobParameters params);
211
212    /**
213     * This method is called if the system has determined that you must stop execution of your job
214     * even before you've had a chance to call {@link #jobFinished(JobParameters, boolean)}.
215     *
216     * <p>This will happen if the requirements specified at schedule time are no longer met. For
217     * example you may have requested WiFi with
218     * {@link android.app.job.JobInfo.Builder#setRequiredNetworkType(int)}, yet while your
219     * job was executing the user toggled WiFi. Another example is if you had specified
220     * {@link android.app.job.JobInfo.Builder#setRequiresDeviceIdle(boolean)}, and the phone left its
221     * idle maintenance window. You are solely responsible for the behaviour of your application
222     * upon receipt of this message; your app will likely start to misbehave if you ignore it. One
223     * immediate repercussion is that the system will cease holding a wakelock for you.</p>
224     *
225     * @param params Parameters specifying info about this job.
226     * @return True to indicate to the JobManager whether you'd like to reschedule this job based
227     * on the retry criteria provided at job creation-time. False to drop the job. Regardless of
228     * the value returned, your job must stop executing.
229     */
230    public abstract boolean onStopJob(JobParameters params);
231
232    /**
233     * Callback to inform the JobManager you've finished executing. This can be called from any
234     * thread, as it will ultimately be run on your application's main thread. When the system
235     * receives this message it will release the wakelock being held.
236     * <p>
237     *     You can specify post-execution behaviour to the scheduler here with
238     *     <code>needsReschedule </code>. This will apply a back-off timer to your job based on
239     *     the default, or what was set with
240     *     {@link android.app.job.JobInfo.Builder#setBackoffCriteria(long, int)}. The original
241     *     requirements are always honoured even for a backed-off job. Note that a job running in
242     *     idle mode will not be backed-off. Instead what will happen is the job will be re-added
243     *     to the queue and re-executed within a future idle maintenance window.
244     * </p>
245     *
246     * @param params Parameters specifying system-provided info about this job, this was given to
247     *               your application in {@link #onStartJob(JobParameters)}.
248     * @param needsReschedule True if this job should be rescheduled according to the back-off
249     *                        criteria specified at schedule-time. False otherwise.
250     */
251    public final void jobFinished(JobParameters params, boolean needsReschedule) {
252        ensureHandler();
253        Message m = Message.obtain(mHandler, MSG_JOB_FINISHED, params);
254        m.arg2 = needsReschedule ? 1 : 0;
255        m.sendToTarget();
256    }
257}