From ee3bcc4c6462d1402e48e9d260e16d038d8fe291 Mon Sep 17 00:00:00 2001
From: Dianne Hackborn
Date: Thu, 15 Apr 2010 11:33:38 -0700
Subject: A little more improvement of the Service javadoc.
Change-Id: I15fb191a26f2ef86a2bf553177cb2d08905adb1c
---
core/java/android/app/Service.java | 52 +++++++++++++++++++++++++++++++++++---
1 file changed, 49 insertions(+), 3 deletions(-)
(limited to 'core/java/android/app/Service.java')
diff --git a/core/java/android/app/Service.java b/core/java/android/app/Service.java
index 6767332..697a987 100644
--- a/core/java/android/app/Service.java
+++ b/core/java/android/app/Service.java
@@ -31,8 +31,9 @@ import java.io.FileDescriptor;
import java.io.PrintWriter;
/**
- * A Service is an application component that runs in the background, not
- * interacting with the user, for an indefinite period of time. Each service
+ * A Service is an application component representing either an application's desire
+ * to perform a longer-running operation while not interacting with the user
+ * or to supply functionality for other applications to use. Each service
* class must have a corresponding
* {@link android.R.styleable#AndroidManifestService <service>}
* declaration in its package's AndroidManifest.xml
. Services
@@ -46,13 +47,16 @@ import java.io.PrintWriter;
* networking) operations, it should spawn its own thread in which to do that
* work. More information on this can be found in
* Application Fundamentals:
- * Processes and Threads.
+ * Processes and Threads. The {@link IntentService} class is available
+ * as a standard implementation of Service that has its own thread where it
+ * schedules its work to be done.
*
* The Service class is an important part of an
* application's overall lifecycle.
*
* Topics covered here:
*
+ * - What is a Service?
*
- Service Lifecycle
*
- Permissions
*
- Process Lifecycle
@@ -60,6 +64,48 @@ import java.io.PrintWriter;
*
- Remote Messenger Service Sample
*
*
+ *
+ * What is a Service?
+ *
+ * Most confusion about the Service class actually revolves around what
+ * it is not:
+ *
+ *
+ * - A Service is not a separate process. The Service object itself
+ * does not imply it is running in its own process; unless otherwise specified,
+ * it runs in the same process as the application it is part of.
+ *
- A Service is not a thread. It is not a means itself to do work off
+ * of the main thread (to avoid Application Not Responding errors).
+ *
+ *
+ * Thus a Service itself is actually very simple, providing two main features:
+ *
+ *
+ * - A facility for the application to tell the system about
+ * something it wants to be doing in the background (even when the user is not
+ * directly interacting with the application). This corresponds to calls to
+ * {@link android.content.Context#startService Context.startService()}, which
+ * ask the system to schedule work for the service, to be run until the service
+ * or someone else explicitly stop it.
+ *
- A facility for an application to expose some of its functionality to
+ * other applications. This corresponds to calls to
+ * {@link android.content.Context#bindService Context.bindService()}, which
+ * allows a long-standing connection to be made to the service in order to
+ * interact with it.
+ *
+ *
+ * When a Service component is actually created, for either of these reasons,
+ * all that the system actually does is instantiate the component
+ * and call its {@link #onCreate} and any other appropriate callbacks on the
+ * main thread. It is up to the Service to implement these with the appropriate
+ * behavior, such as creating a secondary thread in which it does its work.
+ *
+ * Note that because Service itself is so simple, you can make your
+ * interaction with it as simple or complicated as you want: from treating it
+ * as a local Java object that you make direct method calls on (as illustrated
+ * by Local Service Sample), to providing
+ * a full remoteable interface using AIDL.
+ *
*
* Service Lifecycle
*
--
cgit v1.1