Improve Service documentation with some samples.

 * <li><a href="#ServiceLifecycle">Service Lifecycle</a>

 * <li><a href="#Permissions">Permissions</a>

 * <li><a href="#ProcessLifecycle">Process Lifecycle</a>

 * <li><a href="#LocalServiceSample">Local Service Sample</a>

 * <li><a href="#RemoteMessengerServiceSample">Remote Messenger Service Sample</a>

 * </ol>

 * 

 * <a name="ServiceLifecycle"></a>

 * (such as an {@link android.app.Activity}) can, of course, increase the

 * importance of the overall

 * process beyond just the importance of the service itself.

 * 

 * <a name="LocalServiceSample"></a>

 * <h3>Local Service Sample</h3>

 * 

 * <p>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.

 * 

 * <p>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.

 * 

 * <p>An example of this use of a Service is shown here.  First is the Service

 * itself, publishing a custom class when bound:

 * 

 * {@sample development/samples/ApiDemos/src/com/example/android/apis/app/LocalService.java

 *      service}

 * 

 * <p>With that done, one can now write client code that directly accesses the

 * running service, such as:

 * 

 * {@sample development/samples/ApiDemos/src/com/example/android/apis/app/LocalServiceActivities.java

 *      bind}

 * 

 * <a name="RemoteMessengerServiceSample"></a>

 * <h3>Remote Messenger Service Sample</h3>

 * 

 * <p>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

 * {@link Context#startService(Intent) Context.startService} to send

 * commands to it), then you can use the {@link android.os.Messenger} class

 * instead of writing full AIDL files.

 * 

 * <p>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:

 * 

 * {@sample development/samples/ApiDemos/src/com/example/android/apis/app/MessengerService.java

 *      service}

 * 

 * <p>If we want to make this service run in a remote process (instead of the

 * standard one for its .apk), we can use <code>android:process</code> in its

 * manifest tag to specify one:

 * 

 * {@sample development/samples/ApiDemos/AndroidManifest.xml remote_service_declaration}

 * 

 * <p>Note that the name "remote" chosen here is arbitrary, and you can use

 * other names if you want additional processes.  The ':' prefix appends the

 * name to your package's standard process name.

 * 

 * <p>With that done, clients can now bind to the service and send messages

 * to it.  Note that this allows clients to register with it to receive

 * messages back as well:

 * 

 * {@sample development/samples/ApiDemos/src/com/example/android/apis/app/MessengerServiceActivities.java

 *      bind}

 */

public abstract class Service extends ContextWrapper implements ComponentCallbacks {

    private static final String TAG = "Service";

     */

    public int what;

    // Use these fields instead of using the class's Bundle if you can. 

    /** arg1 and arg2 are lower-cost alternatives to using {@link #setData(Bundle) setData()}

    if you only need to store a few integer values. */

    /**

     * arg1 and arg2 are lower-cost alternatives to using

     * {@link #setData(Bundle) setData()} if you only need to store a

     * few integer values.

     */

    public int arg1; 

    /** arg1 and arg2 are lower-cost alternatives to using {@link #setData(Bundle) setData()}

    if you only need to store a few integer values.*/ 

    /**

     * arg1 and arg2 are lower-cost alternatives to using

     * {@link #setData(Bundle) setData()} if you only need to store a

     * few integer values.

     */

    public int arg2;

    /** An arbitrary object to send to the recipient.  This must be null when

     * sending messages across processes. */

    /**

     * An arbitrary object to send to the recipient.  When using

     * {@link Messenger} to send the message across processes this can only

     * be non-null if it contains a Parcelable of a framework class (not one

     * implemented by the application).   For other data transfer use

     * {@link #setData}.

     * 

     * <p>Note that Parcelable objects here are not supported prior to

     * the {@link android.os.Build.VERSION_CODES#FROYO} release.

     */

    public Object obj;

    /** Optional Messenger where replies to this message can be sent.

    /**

     * Optional Messenger where replies to this message can be sent.  The

     * semantics of exactly how this is used are up to the sender and

     * receiver.

     */

    public Messenger replyTo;

     * the <em>target</em> {@link Handler} that is receiving this Message to

     * dispatch it.  If

     * not set, the message will be dispatched to the receiving Handler's

     * {@link Handler#handleMessage(Message Handler.handleMessage())}. */

     * {@link Handler#handleMessage(Message Handler.handleMessage())}.

     */

    public Runnable getCallback() {

        return callback;

    }

    /** 

     * Obtains a Bundle of arbitrary data associated with this

     * event, lazily creating it if necessary. Set this value by calling {@link #setData(Bundle)}.

     * event, lazily creating it if necessary. Set this value by calling

     * {@link #setData(Bundle)}.  Note that when transferring data across

     * processes via {@link Messenger}, you will need to set your ClassLoader

     * on the Bundle via {@link Bundle#setClassLoader(ClassLoader)

     * Bundle.setClassLoader()} so that it can instantiate your objects when

     * you retrieve them.

     * @see #peekData()

     * @see #setData(Bundle)

     */

    public Bundle getData() {

        if (data == null) {

    /** 

     * Like getData(), but does not lazily create the Bundle.  A null

     * is returned if the Bundle does not already exist.

     * is returned if the Bundle does not already exist.  See

     * {@link #getData} for further information on this.

     * @see #getData()

     * @see #setData(Bundle)

     */

    public Bundle peekData() {

        return data;

    }

    /** Sets a Bundle of arbitrary data values. Use arg1 and arg1 members 

     * as a lower cost way to send a few simple integer values, if you can. */

    /**

     * Sets a Bundle of arbitrary data values. Use arg1 and arg1 members 

     * as a lower cost way to send a few simple integer values, if you can.

     * @see #getData() 

     * @see #peekData()

     */

    public void setData(Bundle data) {

        this.data = data;

    }

    }

    public void writeToParcel(Parcel dest, int flags) {

        if (obj != null || callback != null) {

        if (callback != null) {

            throw new RuntimeException(

                "Can't marshal objects across processes.");

                "Can't marshal callbacks across processes.");

        }

        dest.writeInt(what);

        dest.writeInt(arg1);

        dest.writeInt(arg2);

        if (obj != null) {

            try {

                Parcelable p = (Parcelable)obj;

                dest.writeInt(1);

                dest.writeParcelable(p, flags);

            } catch (ClassCastException e) {

                throw new RuntimeException(

                    "Can't marshal non-Parcelable objects across processes.");

            }

        } else {

            dest.writeInt(0);

        }

        dest.writeLong(when);

        dest.writeBundle(data);

        Messenger.writeMessengerOrNullToParcel(replyTo, dest);

        what = source.readInt();

        arg1 = source.readInt();

        arg2 = source.readInt();

        if (source.readInt() != 0) {

            obj = source.readParcelable(getClass().getClassLoader());

        }

        when = source.readLong();

        data = source.readBundle();

        replyTo = Messenger.readMessengerOrNullFromParcel(source);