Introduce "IdleService" API to expose idle-time maintenance to apps

When an application wishes to do low-priority background work when the
device is otherwise idle (e.g. in a desk dock overnight), it declares
a service in its manifest that requires this permission:

     android:permission="android.permission.BIND_IDLE_SERVICE

to launch, and which publishes this intent filter:

    <intent-filter>
        <action android:name="android.service.idle.IdleService" />
    </intent-filter>

This string is declared in the API as IdleService.SERVICE_INTERFACE.

The service must be implemented by extending the new "IdleService"
class, which provides the API through which the system will communicate
with the app.

IdleService declares three methods, two of which are lifecycle callbacks
to the service, and the third of which is for the service itself to
invoke when appropriate.  The lifecycle callbacks are

    public abstract boolean onIdleStart();
    public abstract void onIdleStop();

The first of these is a notification to the service that an idle
maintenance interval has begun.  The service can then spin off
whatever non-UI work it wishes.  When the interval is over, or if
the OS determines that idle services should be shut down immediately,
the onIdleStop() method will be invoked.  The service must shut down
any background processing immediately when this method is called.

Both of these methods must return immediately.  However, the OS
holds a wakelock on the application's behalf for the entire period
between the onIdleStart() and onIdleStop() callbacks.  This means
that for system-arbitrated idle-time operation, the application does
not need to do any of its own wakelock management, and does not need
to hold any wakelock permissions.

The third method in IdleService is

    public final void finishIdle();

Calling this method notifies the OS that the application has finished
whatever idle-time operation it needed to perform, and the OS is thus
free to release the wakelock and return to normal operation (or to
allow other apps to run their own idle services).

Currently the idle window granted to each idle service is ten minutes.
The OS is rather conservative about when these services are run; low
battery or any user activity will suppress them, and the OS will not
choose to run them particularly often.

Idle services are granted their execution windows in round-robin
fashion.

Bug 9680213

Change-Id: Idd6f35940c938c31b94aa4269a67870abf7125b6

6 files changed, 246 insertions, 0 deletions

diff --git a/tests/IdleServiceTest/Android.mk b/tests/IdleServiceTest/Android.mk
new file mode 100644
index 0000000..a7879c5
--- /dev/null
+++ b/tests/IdleServiceTest/Android.mk
@@ -0,0 +1,13 @@
+LOCAL_PATH:= $(call my-dir)
+include $(CLEAR_VARS)
+
+LOCAL_MODULE_TAGS := tests
+
+LOCAL_SRC_FILES := $(call all-subdir-java-files)
+
+LOCAL_PACKAGE_NAME := IdleServiceTest
+LOCAL_CERTIFICATE := platform
+
+LOCAL_PROGUARD_ENABLED := disabled
+
+include $(BUILD_PACKAGE)
diff --git a/tests/IdleServiceTest/AndroidManifest.xml b/tests/IdleServiceTest/AndroidManifest.xml
new file mode 100644
index 0000000..16d2324
--- /dev/null
+++ b/tests/IdleServiceTest/AndroidManifest.xml
@@ -0,0 +1,59 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Copyright (C) 2014 The Android Open Source Project
+
+     Licensed under the Apache License, Version 2.0 (the "License");
+     you may not use this file except in compliance with the License.
+     You may obtain a copy of the License at
+
+          http://www.apache.org/licenses/LICENSE-2.0
+
+     Unless required by applicable law or agreed to in writing, software
+     distributed under the License is distributed on an "AS IS" BASIS,
+     WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+     See the License for the specific language governing permissions and
+     limitations under the License.
+-->
+
+<manifest xmlns:android="http://schemas.android.com/apk/res/android"
+        package="com.android.idleservicetest">
+
+    <application>
+        <service android:name="TestService"
+                 android:exported="true"
+                 android:enabled="true"
+                 android:permission="android.permission.BIND_IDLE_SERVICE" >
+            <intent-filter>
+                <action android:name="android.service.idle.IdleService" />
+            </intent-filter>
+        </service>
+
+        <service android:name="CrashingTestService"
+                 android:exported="true"
+                 android:enabled="true"
+                 android:permission="android.permission.BIND_IDLE_SERVICE" >
+            <intent-filter>
+                <action android:name="android.service.idle.IdleService" />
+            </intent-filter>
+        </service>
+
+        <service android:name="TimeoutTestService"
+                 android:exported="true"
+                 android:enabled="true"
+                 android:permission="android.permission.BIND_IDLE_SERVICE" >
+            <intent-filter>
+                <action android:name="android.service.idle.IdleService" />
+            </intent-filter>
+        </service>
+
+        <!-- UnpermissionedTestService should never run because it does
+             not require the necessary permission in its <service> block -->
+        <service android:name="UnpermissionedTestService"
+                 android:exported="true"
+                 android:enabled="true" >
+            <intent-filter>
+                <action android:name="android.service.idle.IdleService" />
+            </intent-filter>
+        </service>
+
+    </application>
+</manifest>
diff --git a/tests/IdleServiceTest/src/com/android/idleservicetest/CrashingTestService.java b/tests/IdleServiceTest/src/com/android/idleservicetest/CrashingTestService.java
new file mode 100644
index 0000000..022ebcf
--- /dev/null
+++ b/tests/IdleServiceTest/src/com/android/idleservicetest/CrashingTestService.java
@@ -0,0 +1,52 @@
+/*
+ * Copyright (C) 2014 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.android.idleservicetest;
+
+import android.app.maintenance.IdleService;
+import android.os.Handler;
+import android.util.Log;
+
+public class CrashingTestService extends IdleService {
+    static final String TAG = "CrashingTestService";
+
+    String mNull = null;
+
+    @Override
+    public boolean onIdleStart() {
+        Log.i(TAG, "Idle maintenance: onIdleStart()");
+
+        Handler h = new Handler();
+        Runnable r = new Runnable() {
+            @Override
+            public void run() {
+                Log.i(TAG, "Explicitly crashing");
+                if (mNull.equals("")) {
+                    Log.i(TAG, "won't happen");
+                }
+            }
+        };
+        Log.i(TAG, "Posting explicit crash in 15 seconds");
+        h.postDelayed(r, 15 * 1000);
+        return true;
+    }
+
+    @Override
+    public void onIdleStop() {
+        Log.i(TAG, "Idle maintenance: onIdleStop()");
+    }
+
+}
diff --git a/tests/IdleServiceTest/src/com/android/idleservicetest/TestService.java b/tests/IdleServiceTest/src/com/android/idleservicetest/TestService.java
new file mode 100644
index 0000000..7e9805f
--- /dev/null
+++ b/tests/IdleServiceTest/src/com/android/idleservicetest/TestService.java
@@ -0,0 +1,48 @@
+/*
+ * Copyright (C) 2014 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.android.idleservicetest;
+
+import android.app.maintenance.IdleService;
+import android.os.Handler;
+import android.util.Log;
+
+public class TestService extends IdleService {
+    static final String TAG = "TestService";
+
+    @Override
+    public boolean onIdleStart() {
+        Log.i(TAG, "Idle maintenance: onIdleStart()");
+
+        Handler h = new Handler();
+        Runnable r = new Runnable() {
+            @Override
+            public void run() {
+                Log.i(TAG, "Explicitly finishing idle");
+                finishIdle();
+            }
+        };
+        Log.i(TAG, "Posting explicit finish in 15 seconds");
+        h.postDelayed(r, 15 * 1000);
+        return true;
+    }
+
+    @Override
+    public void onIdleStop() {
+        Log.i(TAG, "Idle maintenance: onIdleStop()");
+    }
+
+}
diff --git a/tests/IdleServiceTest/src/com/android/idleservicetest/TimeoutTestService.java b/tests/IdleServiceTest/src/com/android/idleservicetest/TimeoutTestService.java
new file mode 100644
index 0000000..b2ba21b
--- /dev/null
+++ b/tests/IdleServiceTest/src/com/android/idleservicetest/TimeoutTestService.java
@@ -0,0 +1,36 @@
+/*
+ * Copyright (C) 2014 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.android.idleservicetest;
+
+import android.app.maintenance.IdleService;
+import android.util.Log;
+
+public class TimeoutTestService extends IdleService {
+    private static final String TAG = "TimeoutTestService";
+
+    @Override
+    public boolean onIdleStart() {
+        Log.i(TAG, "onIdleStart() but anticipating time-slice timeout");
+        return true;
+    }
+
+    @Override
+    public void onIdleStop() {
+        Log.i(TAG, "onIdleStop() so we're done");
+    }
+
+}
diff --git a/tests/IdleServiceTest/src/com/android/idleservicetest/UnpermissionedTestService.java b/tests/IdleServiceTest/src/com/android/idleservicetest/UnpermissionedTestService.java
new file mode 100644
index 0000000..b9fe32b
--- /dev/null
+++ b/tests/IdleServiceTest/src/com/android/idleservicetest/UnpermissionedTestService.java
@@ -0,0 +1,38 @@
+/*
+ * Copyright (C) 2014 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.android.idleservicetest;
+
+import android.app.maintenance.IdleService;
+import android.util.Log;
+
+// Should never be invoked because its manifest declaration does not
+// require the necessary permission.
+public class UnpermissionedTestService extends IdleService {
+    private static final String TAG = "UnpermissionedTestService";
+
+    @Override
+    public boolean onIdleStart() {
+        Log.e(TAG, "onIdleStart() for this service should never be called!");
+        return false;
+    }
+
+    @Override
+    public void onIdleStop() {
+        Log.e(TAG, "onIdleStop() for this service should never be called!");
+    }
+
+}