SdkController: javadoc for new interfaces/classes.

This should explain what's going on.

Change-Id: I328abd139c297dad41dd8cbbdaca8e6c977e30c4

11 files changed, 164 insertions, 13 deletions

diff --git a/apps/SdkController/SdkControllerApp/AndroidManifest.xml b/apps/SdkController/SdkControllerApp/AndroidManifest.xml
index 43dcdde..72725dc 100755
--- a/apps/SdkController/SdkControllerApp/AndroidManifest.xml
+++ b/apps/SdkController/SdkControllerApp/AndroidManifest.xml
@@ -3,7 +3,7 @@
     package="com.android.tools.sdkcontroller"

     android:versionCode="1"

     android:versionName="1.0" >

-    

+

     <uses-sdk

         android:minSdkVersion="7"

         android:targetSdkVersion="15" />

diff --git a/apps/SdkController/SdkControllerApp/res/layout/main.xml b/apps/SdkController/SdkControllerApp/res/layout/main.xml
index 3722206..c2167d3 100755
--- a/apps/SdkController/SdkControllerApp/res/layout/main.xml
+++ b/apps/SdkController/SdkControllerApp/res/layout/main.xml
@@ -14,7 +14,7 @@
  * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the

  * License for the specific language governing permissions and limitations under

  * the License.

- */


+ */

 -->

 

 <RelativeLayout xmlns:android="http://schemas.android.com/apk/res/android"

diff --git a/apps/SdkController/SdkControllerApp/res/layout/sensor_row.xml b/apps/SdkController/SdkControllerApp/res/layout/sensor_row.xml
index ca167a7..e02bae7 100755
--- a/apps/SdkController/SdkControllerApp/res/layout/sensor_row.xml
+++ b/apps/SdkController/SdkControllerApp/res/layout/sensor_row.xml
@@ -1,4 +1,23 @@
 <?xml version="1.0" encoding="utf-8"?>

+<!--

+/*

+ * Copyright (C) 2011 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.

+ */

+-->

+

+<!-- One row per sensor added to the TableLayout from layout/sensors.xml -->

 <TableRow xmlns:android="http://schemas.android.com/apk/res/android"

     xmlns:tools="http://schemas.android.com/tools"

     android:layout_width="fill_parent"

diff --git a/apps/SdkController/SdkControllerApp/src/com/android/tools/sdkcontroller/activities/BaseBindingActivity.java b/apps/SdkController/SdkControllerApp/src/com/android/tools/sdkcontroller/activities/BaseBindingActivity.java
index c94da1e..53e9158 100755
--- a/apps/SdkController/SdkControllerApp/src/com/android/tools/sdkcontroller/activities/BaseBindingActivity.java
+++ b/apps/SdkController/SdkControllerApp/src/com/android/tools/sdkcontroller/activities/BaseBindingActivity.java
@@ -39,10 +39,20 @@ public abstract class BaseBindingActivity extends Activity {
     private ServiceConnection mServiceConnection;
     private ControllerBinder mServiceBinder;
 
+    /**
+     * Returns the binder. Activities can use that to query the controller service.
+     * @return An existing {@link ControllerBinder}.
+     *   The binder is only valid between calls {@link #onServiceConnected()} and
+     *   {@link #onServiceDisconnected()}. Returns null when not valid.
+     */
     public ControllerBinder getServiceBinder() {
         return mServiceBinder;
     }
 
+    /**
+     * Called when the activity resumes.
+     * This automatically binds to the service, starting it as needed.
+     */
     @Override
     protected void onResume() {
         if (DEBUG) Log.d(TAG, "onResume");
@@ -50,6 +60,10 @@ public abstract class BaseBindingActivity extends Activity {
         bindToService();
     }
 
+    /**
+     * Called when the activity is paused.
+     * This automatically unbinds from the service but does not stop it.
+     */
     @Override
     protected void onPause() {
         if (DEBUG) Log.d(TAG, "onPause");
@@ -59,8 +73,24 @@ public abstract class BaseBindingActivity extends Activity {
 
     // ----------
 
+    /**
+     * Called when binding to the service to get the activity's {@link ControllerListener}.
+     * @return A new non-null {@link ControllerListener}.
+     */
     protected abstract ControllerListener createControllerListener();
+
+    /**
+     * Called by the service once the activity is connected (bound) to it.
+     * When this is called, {@link #getServiceBinder()} returns a non-null binder that
+     * can be used by the activity to control the service.
+     */
     protected abstract void onServiceConnected();
+
+    /**
+     * Called by the service when it is disconnected (unbound).
+     * When this is called, {@link #getServiceBinder()} returns a null binder and
+     * the activity should stop using that binder and remove any reference to it.
+     */
     protected abstract void onServiceDisconnected();
 
     /**
@@ -99,7 +129,7 @@ public abstract class BaseBindingActivity extends Activity {
 
     /**
      * Unbinds from the service but does not actually stop the service.
-     * This lets us have it run in the background even if this isn't the active app.
+     * This lets us have it run in the background even if this isn't the active activity.
      */
     protected void unbindFromService() {
         if (mServiceConnection != null) {
diff --git a/apps/SdkController/SdkControllerApp/src/com/android/tools/sdkcontroller/activities/MainActivity.java b/apps/SdkController/SdkControllerApp/src/com/android/tools/sdkcontroller/activities/MainActivity.java
index b221e4f..727cb0e 100755
--- a/apps/SdkController/SdkControllerApp/src/com/android/tools/sdkcontroller/activities/MainActivity.java
+++ b/apps/SdkController/SdkControllerApp/src/com/android/tools/sdkcontroller/activities/MainActivity.java
@@ -32,6 +32,11 @@ import com.android.tools.sdkcontroller.service.ControllerService;
 import com.android.tools.sdkcontroller.service.ControllerService.ControllerBinder;
 import com.android.tools.sdkcontroller.service.ControllerService.ControllerListener;
 
+/**
+ * Main activity. It's the entry point for the application.
+ * It allows the user to start/stop the service and see it's current state and errors.
+ * It also has buttons to start either the sensor control activity or the multitouch activity.
+ */
 public class MainActivity extends BaseBindingActivity {
 
     @SuppressWarnings("hiding")
diff --git a/apps/SdkController/SdkControllerApp/src/com/android/tools/sdkcontroller/activities/MultitouchActivity.java b/apps/SdkController/SdkControllerApp/src/com/android/tools/sdkcontroller/activities/MultitouchActivity.java
index 0e65482..62f5d68 100755
--- a/apps/SdkController/SdkControllerApp/src/com/android/tools/sdkcontroller/activities/MultitouchActivity.java
+++ b/apps/SdkController/SdkControllerApp/src/com/android/tools/sdkcontroller/activities/MultitouchActivity.java
@@ -16,9 +16,14 @@
 

 package com.android.tools.sdkcontroller.activities;

 

+import com.android.tools.sdkcontroller.handlers.MultitouchHandler;

+

 import android.app.Activity;

 import android.os.Bundle;

 

+/**

+ * Activity that controls and displays the {@link MultitouchHandler}.

+ */

 public class MultitouchActivity extends Activity {

 

     public static String TAG = MultitouchActivity.class.getSimpleName();

diff --git a/apps/SdkController/SdkControllerApp/src/com/android/tools/sdkcontroller/activities/SensorActivity.java b/apps/SdkController/SdkControllerApp/src/com/android/tools/sdkcontroller/activities/SensorActivity.java
index 14a1c72..7944e24 100755
--- a/apps/SdkController/SdkControllerApp/src/com/android/tools/sdkcontroller/activities/SensorActivity.java
+++ b/apps/SdkController/SdkControllerApp/src/com/android/tools/sdkcontroller/activities/SensorActivity.java
@@ -36,6 +36,12 @@ import com.android.tools.sdkcontroller.handlers.SensorsHandler.MonitoredSensor;
 import com.android.tools.sdkcontroller.service.ControllerService.ControllerBinder;

 import com.android.tools.sdkcontroller.service.ControllerService.ControllerListener;

 

+/**

+ * Activity that displays and controls the sensors from {@link SensorsHandler}.

+ * For each sensor it displays a checkbox that is enabled if the sensor is supported

+ * by the emulator. The user can select whether the sensor is active. It also displays

+ * data from the sensor when available.

+ */

 public class SensorActivity extends BaseBindingActivity {

 

     @SuppressWarnings("hiding")

@@ -132,7 +138,9 @@ public class SensorActivity extends BaseBindingActivity {
             assert mDisplayedSensors.isEmpty();

             List<MonitoredSensor> sensors = mSensorHandler.getSensors();

             for (MonitoredSensor sensor : sensors) {

-                final TableRow row = (TableRow) inflater.inflate(R.layout.sensor_row, mTableLayout, false);

+                final TableRow row = (TableRow) inflater.inflate(R.layout.sensor_row,

+                                                                 mTableLayout,

+                                                                 false);

                 mTableLayout.addView(row);

                 mDisplayedSensors.put(sensor, new DisplayInfo(sensor, row));

             }

diff --git a/apps/SdkController/SdkControllerApp/src/com/android/tools/sdkcontroller/handlers/BaseHandler.java b/apps/SdkController/SdkControllerApp/src/com/android/tools/sdkcontroller/handlers/BaseHandler.java
index 2db0f43..a89eefd 100755
--- a/apps/SdkController/SdkControllerApp/src/com/android/tools/sdkcontroller/handlers/BaseHandler.java
+++ b/apps/SdkController/SdkControllerApp/src/com/android/tools/sdkcontroller/handlers/BaseHandler.java
@@ -23,35 +23,78 @@ import android.content.Context;
 

 import com.android.tools.sdkcontroller.lib.EmulatorConnection;

 import com.android.tools.sdkcontroller.lib.EmulatorListener;

+import com.android.tools.sdkcontroller.service.ControllerService;

 

 

-

+/**

+ * An abstract base class for all "action handlers".

+ * <p/>

+ * The {@link ControllerService} can deal with several handlers, each have a specific

+ * purpose as described by {@link HandlerType}.

+ */

 public abstract class BaseHandler {

 

+    /**

+     * The type of action that this handler manages.

+     */

     public enum HandlerType {

+        /** A handler to send multitouch events from the device to the emulator and display

+         *  the emulator screen on the device. */

         MultiTouch,

+        /** A handler to send sensor events from the device to the emulaotr. */

         Sensor

     }

 

+    /**

+     * Returns the type of this handler.

+     * @return One of the {@link HandlerType} values.

+     */

     public abstract HandlerType getType();

 

+    /**

+     * The communication port used by this handler to communicate with the emulator.

+     * <p/>

+     * Note that right now we have 2 handlers that each use their own port. The goal is

+     * to move to a single-connection mechanism where all the handlers' data will be

+     * multiplexed on top of a single {@link EmulatorConnection}.

+     *

+     * @return A non-null port value.

+     */

     public abstract int getPort();

 

+    /**

+     * Called once the {@link EmulatorConnection} has been successfully initialized.

+     * <p/>

+     * Note that this will <em>not</em> be called if the {@link EmulatorConnection}

+     * fails to bind to the underlying socket.

+     *

+     * @param connection The connection that has just been created.

+     *   A handler might want to use this to send data to the emulator via

+     *   {@link EmulatorConnection#sendNotification(String)}. However handlers

+     *   need to be particularly careful in <em>not</em> sending network data

+     *   from the main UI thread.

+     * @param context The controller service' context.

+     */

     public abstract void onStart(EmulatorConnection connection, Context context);

 

+    /**

+     * Called once the {@link EmulatorConnection} is being disconnected.

+     */

     public abstract void onStop();

 

     // ------------

     // Interaction from the emulator connection towards the handler

 

     /**

-     * Uses the first non-null replies to this query.

+     * Emulator query being forwarded to the handler.

+     *

      * @see EmulatorListener#onEmulatorQuery(String, String)

      */

     public abstract String onEmulatorQuery(String query, String param);

 

     /**

-     * Uses the first non-null replies to this query.

+     * Emulator blob query being forwarded to the handler.

+     *

      * @see EmulatorListener#onEmulatorBlobQuery(byte[])

      */

     public abstract String onEmulatorBlobQuery(byte[] array);

@@ -59,12 +102,22 @@ public abstract class BaseHandler {
     // ------------

     // Interaction from handler towards listening UI

 

+    /**

+     * Interface to be implemented by activities that use this handler.

+     * This is used by the handler to send event data to any UI.

+     */

     public interface UiListener {

         public void onHandlerEvent(int event, Object...params);

     }

 

     private final List<UiListener> mUiListeners = new ArrayList<UiListener>();

 

+    /**

+     * Registers a new UI listener.

+     *

+     * @param listener A non-null UI listener to register.

+     *   Ignored if the listener is null or already registered.

+     */

     public void addUiListener(UiListener listener) {

         assert listener != null;

         if (listener != null) {

@@ -74,11 +127,24 @@ public abstract class BaseHandler {
         }

     }

 

+

+    /**

+     * Unregisters an UI listener.

+     *

+     * @param listener A non-null UI listener to unregister.

+     *   Ignored if the listener is null or already registered.

+     */

     public void removeUiListener(UiListener listener) {

         assert listener != null;

         mUiListeners.remove(listener);

     }

 

+    /**

+     * Protected method to be used by handlers to send an event to any listening UI.

+     *

+     * @param event The event code. To be defined by the handler itself.

+     * @param params Any parameters that the handler defines for this event.

+     */

     protected void notifyUi(int event, Object...params) {

         for (UiListener listener : mUiListeners) {

             listener.onHandlerEvent(event, params);

diff --git a/apps/SdkController/SdkControllerApp/src/com/android/tools/sdkcontroller/handlers/SensorsHandler.java b/apps/SdkController/SdkControllerApp/src/com/android/tools/sdkcontroller/handlers/SensorsHandler.java
index f6c3068..c10cfdd 100755
--- a/apps/SdkController/SdkControllerApp/src/com/android/tools/sdkcontroller/handlers/SensorsHandler.java
+++ b/apps/SdkController/SdkControllerApp/src/com/android/tools/sdkcontroller/handlers/SensorsHandler.java
@@ -17,7 +17,6 @@
 package com.android.tools.sdkcontroller.handlers;

 

 import java.util.ArrayList;

-import java.util.LinkedList;

 import java.util.List;

 import java.util.concurrent.BlockingQueue;

 import java.util.concurrent.LinkedBlockingDeque;

@@ -465,8 +464,8 @@ public class SensorsHandler extends BaseHandler {
                     mTextFmt = "N/A";

                     mEmulatorFriendlyName = "unknown";

                     mMsgFmt = mEmulatorFriendlyName + "\0";

-                    if (DEBUG) Log.e(TAG, "Unknown sensor type " + mSensor.getType() + " for sensor "

-                            + mSensor.getName());

+                    if (DEBUG) Log.e(TAG, "Unknown sensor type " + mSensor.getType() +

+                            " for sensor " + mSensor.getName());

                     break;

             }

         }

@@ -576,7 +575,7 @@ public class SensorsHandler extends BaseHandler {
                 String msg;

                 String val;

                 if (nArgs == 3) {

-                    val = String.format(mTextFmt, event.values[0], event.values[1], event.values[2]);

+                    val = String.format(mTextFmt, event.values[0], event.values[1],event.values[2]);

                     msg = String.format(mMsgFmt, event.values[0], event.values[1], event.values[2]);

                 } else if (nArgs == 2) {

                     val = String.format(mTextFmt, event.values[0], event.values[1]);

diff --git a/apps/SdkController/SdkControllerApp/src/com/android/tools/sdkcontroller/service/ControllerService.java b/apps/SdkController/SdkControllerApp/src/com/android/tools/sdkcontroller/service/ControllerService.java
index 9f006cb..05cf5fb 100755
--- a/apps/SdkController/SdkControllerApp/src/com/android/tools/sdkcontroller/service/ControllerService.java
+++ b/apps/SdkController/SdkControllerApp/src/com/android/tools/sdkcontroller/service/ControllerService.java
@@ -44,6 +44,22 @@ import com.android.tools.sdkcontroller.lib.EmulatorListener;
 /**

  * The background service of the SdkController.

  * There can be only one instance of this.

+ * <p/>

+ * The service manages a number of action "handlers" which can be seen as individual tasks

+ * that the user might want to accomplish, for example "sending sensor data to the emulator"

+ * or "sending multitouch data and displaying an emulator screen".

+ * <p/>

+ * Each handler currently has its own emulator connection associated to it (cf class

+ * {@cpde EmuCnxHandler} below. However our goal is to later move to a single connection channel

+ * with all data multiplexed on top of it.

+ * <p/>

+ * All the handlers are created when the service starts, and whether the emulator connection

+ * is successful or not, and whether there's any UI to control it. It's up to the handlers

+ * to deal with these specific details. <br/>

+ * For example the {@link SensorsHandler} initializes its sensor list as soon as created

+ * and then tries to send data as soon as there's an emulator connection.

+ * On the other hand the {@link MultitouchHandler} lays dormant till there's an UI interacting

+ * with it.

  */

 public class ControllerService extends Service {

 

@@ -55,6 +71,7 @@ public class ControllerService extends Service {
     public static String TAG = ControllerService.class.getSimpleName();

     private static boolean DEBUG = true;

 

+    /** Identifier for the notification. */

     private static int NOTIF_ID = 'S' << 24 + 'd' << 16 + 'k' << 8 + 'C' << 0;

 

     private final IBinder mBinder = new ControllerBinder();

diff --git a/apps/SdkController/SdkControllerLib/src/com/android/tools/sdkcontroller/lib/EmulatorListener.java b/apps/SdkController/SdkControllerLib/src/com/android/tools/sdkcontroller/lib/EmulatorListener.java
index f707822..4d2a19f 100644
--- a/apps/SdkController/SdkControllerLib/src/com/android/tools/sdkcontroller/lib/EmulatorListener.java
+++ b/apps/SdkController/SdkControllerLib/src/com/android/tools/sdkcontroller/lib/EmulatorListener.java
@@ -16,6 +16,7 @@
 
 package com.android.tools.sdkcontroller.lib;
 
+
 /**
  * Encapsulates a listener to emulator events. An object implementing this
  * interface must be registered with the EmulatorConnection instance via
@@ -24,10 +25,11 @@ package com.android.tools.sdkcontroller.lib;
 public interface EmulatorListener {
 
     /**
-     * Called as a side effect of constructing a new {@link EmulatorConnection}
-     * when emulator is bound with its communication socket.
+     * Called as a side effect of constructing a new {@link EmulatorConnection} to
+     * indicate whether the when emulator is bound with its communication socket.
      *
      * @param success True if the socket bind was successful.
+     *   False when the socket bind failed.
      * @param e Any exception thrown whilst trying to bind to the communication socket.
      *   Null if there's no exception (typically when {@code success==true}).
      */