Clarified conditions that require client-side unbindService() call.

The documentation for android.app.Service includes an example from
LocalServiceActivities.java. This example now better shows and
explains the distinction between binding and connecting. It also
shows the set of conditions that require the client to call
unbindService().

Test: make ds-docs -j16

Bug: 63118511
Change-Id: I1276de3f9421e13e1964039d37db9adc87f3039f

samples/ApiDemos/src/com/example/android/apis/app/LocalServiceActivities.java

@@ -23,6 +23,7 @@ import android.content.ComponentName;
 import android.content.Context;
 import android.content.Intent;
 import android.content.ServiceConnection;
+import android.util.Log;
 import android.os.Bundle;
 import android.os.IBinder;
 import android.view.View;
@@ -89,8 +90,13 @@ public class LocalServiceActivities {
      * all together; typically this code would appear in some separate class.
      */
     public static class Binding extends Activity {
-        private boolean mIsBound;
+// BEGIN_INCLUDE(bind)
+        // Don't attempt to unbind from the service unless the client has received some
+        // information about the service's state.
+        private boolean mShouldUnbind;
 
+        // To invoke the bound service, first make sure that this value
+        // is not null.
         private LocalService mBoundService;
 
         private ServiceConnection mConnection = new ServiceConnection() {
@@ -119,20 +125,25 @@ public class LocalServiceActivities {
         };
 
         void doBindService() {
-            // Establish a connection with the service.  We use an explicit
-            // class name because we want a specific service implementation that
-            // we know will be running in our own process (and thus won't be
-            // supporting component replacement by other applications).
-            bindService(new Intent(Binding.this, 
-                    LocalService.class), mConnection, Context.BIND_AUTO_CREATE);
-            mIsBound = true;
+            // Attempts to establish a connection with the service.  We use an
+            // explicit class name because we want a specific service
+            // implementation that we know will be running in our own process
+            // (and thus won't be supporting component replacement by other
+            // applications).
+            if (bindService(new Intent(Binding.this, LocalService.class),
+                    mConnection, Context.BIND_AUTO_CREATE)) {
+                mShouldUnbind = true;
+            } else {
+                Log.e("MY_APP_TAG", "Error: The requested service doesn't " +
+                        "exist, or this client isn't allowed access to it.");
+            }
         }
 
         void doUnbindService() {
-            if (mIsBound) {
-                // Detach our existing connection.
+            if (mShouldUnbind) {
+                // Release information about the service's state.
                 unbindService(mConnection);
-                mIsBound = false;
+                mShouldUnbind = false;
             }
         }