/**
* 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
* declaration in its package's <code>AndroidManifest.xml
* Services can be started with
* android.content.Context#startService Context.startService() and
* android.content.Context#bindService Context.bindService().
*
* Note that services, like other application objects, run in the main
* thread of their hosting process. This means that, if your service is going
* to do any CPU intensive (such as MP3 playback) or blocking (such as
* networking) operations, it should spawn its own thread in which to do that
* work.
* IntentService class is available
* as a standard implementation of Service that has its own thread where it
* schedules its work to be done.
*
* Topics covered here:
* What is a Service?
* Service Lifecycle
* Permissions
* Process Lifecycle
* Local Service Sample
* Remote Messenger Service Sample
*
* 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:
* directly interacting with the application). This corresponds to calls to
* {android.content.Context#startService Context.startService()}, which
* ask the system to schedule work for the service, to be run until the service
* {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 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 to providing
* a full remoteable interface using AIDL.
*
* calls {android.content.Context#startService Context.startService()} then the system will
* retrieve the service (creating it and calling its {onCreate} method
* if needed) and then call its {onStartCommand} method with the
* arguments supplied by the client. The service will at this point continue
* running until {android.content.Context#stopService Context.stopService()} or
* {stopSelf()} is called. Note that multiple calls to
* Context.startService() do not nest (though they do result in multiple corresponding
* calls to onStartCommand()), so no matter how many times it is started a service
* will be stopped once Context.stopService() or stopSelf() is called; however,
* services can use their { #stopSelf(int)} method to ensure the service is
* not stopped until started intents have been processed.
*
* For started services, there are two additional major modes of operation
* they can decide to run in, depending on the value they return from
* onStartCommand(): {START_STICKY} is used for services that are
* explicitly started and stopped as needed, while {START_NOT_STICKY}
* or {START_REDELIVER_INTENT} are used for services that should only
* remain running while processing any commands sent to them. See the linked
* documentation for more detail on the semantics.
*
* obtain a persistent connection to a service. This likewise creates the
* service if it is not already running (calling {@link #onCreate} while
* doing so), but does not call onStartCommand(). The client will receive the
* {android.os.IBinder} object that the service returns from its
* {onBind} method, allowing the client to then make calls back
* to the service. The service will remain running as long as the connection
* is established (whether or not the client retains a reference on the
* service's IBinder). Usually the IBinder returned is for a complex
* interface.
*
* A service can be both started and have connections bound to it. In such
* a case, the system will keep the service running as long as either it is
* started or there are one or more connections to it with the
* {android.content.Context#BIND_AUTO_CREATE Context.BIND_AUTO_CREATE}
* flag.
* Once neither
* of these situations hold, the service's {@link #onDestroy} method is called
* and the service is effectively terminated. All cleanup (stopping threads,
* unregistering receivers) should be complete upon returning from onDestroy().
*
* Global access to a service can be enforced when it is declared in its
* manifest's tag.
* By doing so, other applications will need to declare a corresponding
* element in their own manifest to be able to start, stop, or bind to
* the service.
*
* When using
* {Context#startService(Intent) Context.startService(Intent)}, you can
* also set {Intent#FLAG_GRANT_READ_URI_PERMISSION
* Intent.FLAG_GRANT_READ_URI_PERMISSION} and/or {Intent#FLAG_GRANT_WRITE_URI_PERMISSION
* Intent.FLAG_GRANT_WRITE_URI_PERMISSION} on the Intent. This will grant the
* Service temporary access to the specific URIs in the Intent. Access will
* remain until the Service has called {stopSelf(int)} for that start
* command or a later one, or until the Service has been completely stopped.
* This works for granting access to the other apps that have not requested
* the permission protecting the Service, or even when the Service is not
* exported at all.
*
* In addition, a service can protect individual IPC calls into it with
* permissions, by calling the
* {checkCallingPermission}
* method before executing the implementation of that call.
* around as long as the service has been started or has clients bound to it.
* When running low on memory and needing to kill existing processes, the
* priority of a process hosting the service will be the higher of the
* following possibilities:
*
* If the service is currently executing code in its
* {onCreate()}, {onStartCommand()},
* or {onDestroy()} methods, then the hosting process will
* be a foreground process to ensure this code can execute without being killed.
* If the service has been started, then its hosting process is considered
* to be less important than any processes that are currently visible to the
* user on-screen, but more important than any process not visible. Because
* only a few processes are generally visible to the user, this means that
* the service should not be killed except in low memory conditions. However, since
* the user is not directly aware of a background service, in that state it is
* considered a valid candidate to kill, and you should be prepared for this to
* happen. In particular, long-running services will be increasingly likely to
* kill and are guaranteed to be killed (and restarted if appropriate) if they
* remain started long enough.
* If there are clients bound to the service, then the service's hosting
* process is never less important than the most important client. That is,
* if one of its clients is visible to the user, then the service itself is
* considered to be visible.
*
* Note this means that most of the time your service is running, it may
* be killed by the system if it is under heavy memory pressure. If this
* happens, the system will later try to restart the service. An important
* consequence of this is that if you implement {onStartCommand()}
* to schedule work to be done asynchronously or in another thread, then you
* may want to use {START_FLAG_REDELIVERY} to have the system
* re-deliver an Intent for you so that it does not get lost if your service
* is killed while processing it.
*
* Other application components running in the same process as the service
* (such as an {android.app.Activity}) can, of course, increase the
* importance of the overall
* process beyond just the importance of the service itself.
*
* running alongside other parts of an application, in the same process as
* the rest of the components. All components of an .apk run in the same
* process unless explicitly stated otherwise, so this is a typical situation.
*
* When used in this way, by assuming the
* components are in the same process, you can greatly simplify the interaction
* between them: clients of the service can simply cast the IBinder they
* receive from it to a concrete class published by the service.
*
* An example of this use of a Service is shown here. First is the Service
* itself, publishing a custom class when bound:
*
* {development/samples/ApiDemos/src/com/example/android/apis/app/LocalService.java}
* With that done, one can now write client code that directly accesses the
* running service, such as:
* {development/samples/ApiDemos/src/com/example/android/apis/app/LocalServiceActivities.java}
*
* communication with clients in remote processes (beyond simply the use of
* {startService(Intent) Context.startService} to send
* commands to it), then you can use the {android.os.Messenger} class
* instead of writing full AIDL files.
*
* An example of a Service that uses Messenger as its client interface
* is shown here. First is the Service itself, publishing a Messenger to
* an internal Handler when bound:
*
* {development/samples/ApiDemos/src/com/example/android/apis/app/MessengerService.java
* 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
* declaration in its package's <code>AndroidManifest.xml
* Services can be started with
* android.content.Context#startService Context.startService() and
* android.content.Context#bindService Context.bindService().
*
* Note that services, like other application objects, run in the main
* thread of their hosting process. This means that, if your service is going
* to do any CPU intensive (such as MP3 playback) or blocking (such as
* networking) operations, it should spawn its own thread in which to do that
* work.
* IntentService class is available
* as a standard implementation of Service that has its own thread where it
* schedules its work to be done.
*
* Topics covered here:
* What is a Service?
* Service Lifecycle
* Permissions
* Process Lifecycle
* Local Service Sample
* Remote Messenger Service Sample
*
* 1] What is a service?
* 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:
* 1.1] A facility doing in the background
* 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
* {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
* 1.2] A facility to expose some functionality
* A facility for an application to expose some of its functionality to
* other applications. This corresponds to calls to* {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 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 to providing
* a full remoteable interface using AIDL.
*
* 2] Service Lifecycle
* 2.1] startService -> onCreate -> onStartCommand
* There are two reasons that a service can be run by the system. If someone* calls {android.content.Context#startService Context.startService()} then the system will
* retrieve the service (creating it and calling its {onCreate} method
* if needed) and then call its {onStartCommand} method with the
* arguments supplied by the client. The service will at this point continue
* running until {android.content.Context#stopService Context.stopService()} or
* {stopSelf()} is called. Note that multiple calls to
* Context.startService() do not nest (though they do result in multiple corresponding
* calls to onStartCommand()), so no matter how many times it is started a service
* will be stopped once Context.stopService() or stopSelf() is called; however,
* services can use their { #stopSelf(int)} method to ensure the service is
* not stopped until started intents have been processed.
*
* For started services, there are two additional major modes of operation
* they can decide to run in, depending on the value they return from
* onStartCommand(): {START_STICKY} is used for services that are
* explicitly started and stopped as needed, while {START_NOT_STICKY}
* or {START_REDELIVER_INTENT} are used for services that should only
* remain running while processing any commands sent to them. See the linked
* documentation for more detail on the semantics.
*
* 2.2] bindService
* Clients can also use {android.content.Context#bindService Context.bindService()} to* obtain a persistent connection to a service. This likewise creates the
* service if it is not already running (calling {@link #onCreate} while
* doing so), but does not call onStartCommand(). The client will receive the
* {android.os.IBinder} object that the service returns from its
* {onBind} method, allowing the client to then make calls back
* to the service. The service will remain running as long as the connection
* is established (whether or not the client retains a reference on the
* service's IBinder). Usually the IBinder returned is for a complex
* interface.
*
* A service can be both started and have connections bound to it. In such
* a case, the system will keep the service running as long as either it is
* started or there are one or more connections to it with the
* {android.content.Context#BIND_AUTO_CREATE Context.BIND_AUTO_CREATE}
* flag.
* Once neither
* of these situations hold, the service's {@link #onDestroy} method is called
* and the service is effectively terminated. All cleanup (stopping threads,
* unregistering receivers) should be complete upon returning from onDestroy().
*
* 3] Permissions
** Global access to a service can be enforced when it is declared in its
* manifest's tag.
* By doing so, other applications will need to declare a corresponding
* element in their own manifest to be able to start, stop, or bind to
* the service.
*
* When using
* {Context#startService(Intent) Context.startService(Intent)}, you can
* also set {Intent#FLAG_GRANT_READ_URI_PERMISSION
* Intent.FLAG_GRANT_READ_URI_PERMISSION} and/or {Intent#FLAG_GRANT_WRITE_URI_PERMISSION
* Intent.FLAG_GRANT_WRITE_URI_PERMISSION} on the Intent. This will grant the
* Service temporary access to the specific URIs in the Intent. Access will
* remain until the Service has called {stopSelf(int)} for that start
* command or a later one, or until the Service has been completely stopped.
* This works for granting access to the other apps that have not requested
* the permission protecting the Service, or even when the Service is not
* exported at all.
*
* In addition, a service can protect individual IPC calls into it with
* permissions, by calling the
* {checkCallingPermission}
* method before executing the implementation of that call.
* 4] Process Lifecycle
* The Android system will attempt to keep the process hosting a service* around as long as the service has been started or has clients bound to it.
* When running low on memory and needing to kill existing processes, the
* priority of a process hosting the service will be the higher of the
* following possibilities:
*
* If the service is currently executing code in its
* {onCreate()}, {onStartCommand()},
* or {onDestroy()} methods, then the hosting process will
* be a foreground process to ensure this code can execute without being killed.
* If the service has been started, then its hosting process is considered
* to be less important than any processes that are currently visible to the
* user on-screen, but more important than any process not visible. Because
* only a few processes are generally visible to the user, this means that
* the service should not be killed except in low memory conditions. However, since
* the user is not directly aware of a background service, in that state it is
* considered a valid candidate to kill, and you should be prepared for this to
* happen. In particular, long-running services will be increasingly likely to
* kill and are guaranteed to be killed (and restarted if appropriate) if they
* remain started long enough.
* If there are clients bound to the service, then the service's hosting
* process is never less important than the most important client. That is,
* if one of its clients is visible to the user, then the service itself is
* considered to be visible.
*
* Note this means that most of the time your service is running, it may
* be killed by the system if it is under heavy memory pressure. If this
* happens, the system will later try to restart the service. An important
* consequence of this is that if you implement {onStartCommand()}
* to schedule work to be done asynchronously or in another thread, then you
* may want to use {START_FLAG_REDELIVERY} to have the system
* re-deliver an Intent for you so that it does not get lost if your service
* is killed while processing it.
*
* Other application components running in the same process as the service
* (such as an {android.app.Activity}) can, of course, increase the
* importance of the overall
* process beyond just the importance of the service itself.
*
* 5] Local Service Sample
* One of the most common uses of a Service is as a secondary component* running alongside other parts of an application, in the same process as
* the rest of the components. All components of an .apk run in the same
* process unless explicitly stated otherwise, so this is a typical situation.
*
* When used in this way, by assuming the
* components are in the same process, you can greatly simplify the interaction
* between them: clients of the service can simply cast the IBinder they
* receive from it to a concrete class published by the service.
*
* An example of this use of a Service is shown here. First is the Service
* itself, publishing a custom class when bound:
*
* {development/samples/ApiDemos/src/com/example/android/apis/app/LocalService.java}
* With that done, one can now write client code that directly accesses the
* running service, such as:
* {development/samples/ApiDemos/src/com/example/android/apis/app/LocalServiceActivities.java}
*
* 6] Remote Messenger Service Sample
* If you need to be able to write a Service that can perform complicated* communication with clients in remote processes (beyond simply the use of
* {startService(Intent) Context.startService} to send
* commands to it), then you can use the {android.os.Messenger} class
* instead of writing full AIDL files.
*
* An example of a Service that uses Messenger as its client interface
* is shown here. First is the Service itself, publishing a Messenger to
* an internal Handler when bound:
*
* {development/samples/ApiDemos/src/com/example/android/apis/app/MessengerService.java
* service}
*/
public abstract class Service extends ContextWrapper implements ComponentCallbacks2 {｝