Control API review changes

* Add documentation to Device types
* Replace singletons in ControlAction and ControlTemplate to getter
static functions.
* Add javadoc for MODES and FLAG_MODE in TemperatureControlTemplate.
* Removed ThumbnailTemplate instead of updated javadocs. Determined
not necessary anymore
* Remove MultiFloatAction - no longer needed
* Removed reliant sysui code

Bug: 150630500
Test: atest ControlTemplateTest ControlActionTest
Change-Id: Ic4f60c789ce959205137944380e78622d76581a4

8 files changed, 119 insertions, 220 deletions

diff --git a/core/java/android/service/controls/Control.java b/core/java/android/service/controls/Control.java
index dabd9773ec92..d01bc2524332 100644
--- a/core/java/android/service/controls/Control.java
+++ b/core/java/android/service/controls/Control.java
@@ -395,7 +395,7 @@ public final class Control implements Parcelable {
      * {@link ControlsProviderService#createPublisherForAllAvailable}:
      * <ul>
      *     <li> Status: {@link Status#STATUS_UNKNOWN}
-     *     <li> Control template: {@link ControlTemplate#NO_TEMPLATE}
+     *     <li> Control template: {@link ControlTemplate#getNoTemplateObject}
      *     <li> Status text: {@code ""}
      * </ul>
      */
@@ -593,7 +593,7 @@ public final class Control implements Parcelable {
      *     <li> Title: {@code ""}
      *     <li> Subtitle: {@code ""}
      *     <li> Status: {@link Status#STATUS_UNKNOWN}
-     *     <li> Control template: {@link ControlTemplate#NO_TEMPLATE}
+     *     <li> Control template: {@link ControlTemplate#getNoTemplateObject}
      *     <li> Status text: {@code ""}
      * </ul>
      */
diff --git a/core/java/android/service/controls/ControlsProviderService.java b/core/java/android/service/controls/ControlsProviderService.java
index 9debb37bd0bc..9accf5b0abf5 100644
--- a/core/java/android/service/controls/ControlsProviderService.java
+++ b/core/java/android/service/controls/ControlsProviderService.java
@@ -239,7 +239,8 @@ public abstract class ControlsProviderService extends Service {
 
     private static boolean isStatelessControl(Control control) {
         return (control.getStatus() == Control.STATUS_UNKNOWN
-                && control.getControlTemplate().getTemplateType() == ControlTemplate.TYPE_NONE
+                && control.getControlTemplate().getTemplateType()
+                == ControlTemplate.TYPE_NO_TEMPLATE
                 && TextUtils.isEmpty(control.getStatusText()));
     }
 
diff --git a/core/java/android/service/controls/DeviceTypes.java b/core/java/android/service/controls/DeviceTypes.java
index 6594d2cf4ba2..1792a7f52566 100644
--- a/core/java/android/service/controls/DeviceTypes.java
+++ b/core/java/android/service/controls/DeviceTypes.java
@@ -23,6 +23,18 @@ import java.lang.annotation.RetentionPolicy;
 
 /**
  * Device types for {@link Control}.
+ *
+ * Each {@link Control} declares a type for the device they represent. This type will be used to
+ * determine icons and colors.
+ * <p>
+ * The type of the device may change on status updates of the {@link Control}. For example, a
+ * device of {@link #TYPE_OUTLET} could be determined by the {@link ControlsProviderService} to be
+ * a {@link #TYPE_COFFEE_MAKER} and change the type for that {@link Control}, therefore possibly
+ * changing icon and color.
+ * <p>
+ * In case the device type is not know by the application but the basic function is, or there is no
+ * provided type, one of the generic types (those starting with {@code TYPE_GENERIC}) can be used.
+ * These will provide an identifiable icon based on the basic function of the device.
  */
 public class DeviceTypes {
 
diff --git a/core/java/android/service/controls/actions/ControlAction.java b/core/java/android/service/controls/actions/ControlAction.java
index 45e63d772d73..37a75f0e9e5a 100644
--- a/core/java/android/service/controls/actions/ControlAction.java
+++ b/core/java/android/service/controls/actions/ControlAction.java
@@ -22,7 +22,7 @@ import android.annotation.NonNull;
 import android.annotation.Nullable;
 import android.os.Bundle;
 import android.service.controls.Control;
-import android.service.controls.IControlsActionCallback;
+import android.service.controls.ControlsProviderService;
 import android.service.controls.templates.ControlTemplate;
 import android.util.Log;
 
@@ -34,8 +34,15 @@ import java.lang.annotation.RetentionPolicy;
 /**
  * An abstract action indicating a user interaction with a {@link Control}.
  *
- * The action may have a value to authenticate the input, when the provider has requested it to
- * complete the action.
+ * In some cases, an action needs to be validated by the user, using a password, PIN or simple
+ * acknowledgment. For those cases, an optional (nullable) parameter can be passed to send the user
+ * input. This <b>challenge value</b> will be requested from the user and sent as part
+ * of a {@link ControlAction} only if the service has responded to an action with one of:
+ * <ul>
+ *     <li> {@link #RESPONSE_CHALLENGE_ACK}
+ *     <li> {@link #RESPONSE_CHALLENGE_PIN}
+ *     <li> {@link #RESPONSE_CHALLENGE_PASSPHRASE}
+ * </ul>
  */
 public abstract class ControlAction {
 
@@ -53,7 +60,6 @@ public abstract class ControlAction {
             TYPE_ERROR,
             TYPE_BOOLEAN,
             TYPE_FLOAT,
-            TYPE_MULTI_FLOAT,
             TYPE_MODE,
             TYPE_COMMAND
     })
@@ -61,6 +67,7 @@ public abstract class ControlAction {
 
     /**
      * Object returned when there is an unparcelling error.
+     * @hide
      */
     public static final @NonNull ControlAction ERROR_ACTION = new ControlAction() {
         @Override
@@ -70,7 +77,7 @@ public abstract class ControlAction {
     };
 
     /**
-     * The identifier of {@link #ERROR_ACTION}
+     * The identifier of the action returned by {@link #getErrorAction}.
      */
     public static final @ActionType int TYPE_ERROR = -1;
 
@@ -85,11 +92,6 @@ public abstract class ControlAction {
     public static final @ActionType int TYPE_FLOAT = 2;
 
     /**
-     * The identifier of {@link MultiFloatAction}.
-     */
-    public static final @ActionType int TYPE_MULTI_FLOAT = 3;
-
-    /**
      * The identifier of {@link ModeAction}.
      */
     public static final @ActionType int TYPE_MODE = 4;
@@ -121,28 +123,32 @@ public abstract class ControlAction {
     public static final @ResponseResult int RESPONSE_UNKNOWN = 0;
 
     /**
-     * Response code for {@link IControlsActionCallback#accept} indicating that
-     * the action has been performed. The action may still fail later and the state may not change.
+     * Response code for the {@code consumer} in
+     * {@link ControlsProviderService#performControlAction} indicating that the action has been
+     * performed. The action may still fail later and the state may not change.
      */
     public static final @ResponseResult int RESPONSE_OK = 1;
     /**
-     * Response code for {@link IControlsActionCallback#accept} indicating that
-     * the action has failed.
+     * Response code for the {@code consumer} in
+     * {@link ControlsProviderService#performControlAction} indicating that the action has failed.
      */
     public static final @ResponseResult int RESPONSE_FAIL = 2;
     /**
-     * Response code for {@link IControlsActionCallback#accept} indicating that
-     * in order for the action to be performed, acknowledgment from the user is required.
+     * Response code for the {@code consumer} in
+     * {@link ControlsProviderService#performControlAction} indicating that in order for the action
+     * to be performed, acknowledgment from the user is required.
      */
     public static final @ResponseResult int RESPONSE_CHALLENGE_ACK = 3;
     /**
-     * Response code for {@link IControlsActionCallback#accept} indicating that
-     * in order for the action to be performed, a PIN is required.
+     * Response code for the {@code consumer} in
+     * {@link ControlsProviderService#performControlAction} indicating that in order for the action
+     * to be performed, a PIN is required.
      */
     public static final @ResponseResult int RESPONSE_CHALLENGE_PIN = 4;
     /**
-     * Response code for {@link IControlsActionCallback#accept} indicating that
-     * in order for the action to be performed, an alphanumeric passphrase is required.
+     * Response code for the {@code consumer} in
+     * {@link ControlsProviderService#performControlAction} indicating that in order for the action
+     * to be performed, an alphanumeric passphrase is required.
      */
     public static final @ResponseResult int RESPONSE_CHALLENGE_PASSPHRASE = 5;
 
@@ -228,8 +234,6 @@ public abstract class ControlAction {
                     return new BooleanAction(bundle);
                 case TYPE_FLOAT:
                     return new FloatAction(bundle);
-                case TYPE_MULTI_FLOAT:
-                    return new MultiFloatAction(bundle);
                 case TYPE_MODE:
                     return new ModeAction(bundle);
                 case TYPE_COMMAND:
@@ -243,4 +247,12 @@ public abstract class ControlAction {
             return ERROR_ACTION;
         }
     }
+
+    /**
+     * Returns a singleton {@link ControlAction} used for indicating an error in unparceling.
+     */
+    @NonNull
+    public static ControlAction getErrorAction() {
+        return ERROR_ACTION;
+    }
 }
diff --git a/core/java/android/service/controls/actions/MultiFloatAction.java b/core/java/android/service/controls/actions/MultiFloatAction.java
deleted file mode 100644
index e5740795ab90..000000000000
--- a/core/java/android/service/controls/actions/MultiFloatAction.java
+++ /dev/null
@@ -1,82 +0,0 @@
-/*
- * Copyright (C) 2019 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.
- */
-
-package android.service.controls.actions;
-
-import android.annotation.NonNull;
-import android.annotation.Nullable;
-import android.os.Bundle;
-import android.util.Log;
-
-import com.android.internal.util.Preconditions;
-
-public final class MultiFloatAction extends ControlAction {
-
-    private static final String TAG = "MultiFloatAction";
-    private static final @ActionType int TYPE = TYPE_MULTI_FLOAT;
-    private static final String KEY_VALUES = "key_values";
-
-    private final @NonNull float[] mNewValues;
-
-    @Override
-    public int getActionType() {
-        return TYPE;
-    }
-
-    public MultiFloatAction(@NonNull String templateId,
-            @NonNull float[] newValues,
-            @Nullable String challengeValue) {
-        super(templateId, challengeValue);
-        Preconditions.checkNotNull(newValues);
-        if (newValues.length == 0) {
-            throw new IllegalArgumentException("newValues array length 0");
-        }
-        if (newValues.length == 1) {
-            Log.w(TAG, "newValues array length 1");
-        }
-        mNewValues = newValues.clone();
-    }
-
-    public MultiFloatAction(@NonNull String templateId, @NonNull float[] newValues) {
-        this(templateId, newValues, null);
-    }
-
-    /**
-     * @param b
-     * @hide
-     */
-    MultiFloatAction(Bundle b) {
-        super(b);
-        mNewValues = b.getFloatArray(KEY_VALUES);
-    }
-
-    @NonNull
-    public float[] getNewValues() {
-        return mNewValues.clone();
-    }
-
-    /**
-     * @return
-     * @hide
-     */
-    @Override
-    @NonNull
-    Bundle getDataBundle() {
-        Bundle b = super.getDataBundle();
-        b.putFloatArray(KEY_VALUES, mNewValues);
-        return b;
-    }
-}
diff --git a/core/java/android/service/controls/templates/ControlTemplate.java b/core/java/android/service/controls/templates/ControlTemplate.java
index 30efd80db106..1e16273c455b 100644
--- a/core/java/android/service/controls/templates/ControlTemplate.java
+++ b/core/java/android/service/controls/templates/ControlTemplate.java
@@ -49,18 +49,20 @@ public abstract class ControlTemplate {
 
     /**
      * Singleton representing a {@link Control} with no input.
+     * @hide
      */
     public static final @NonNull ControlTemplate NO_TEMPLATE = new ControlTemplate("") {
         @Override
         public int getTemplateType() {
-            return TYPE_NONE;
+            return TYPE_NO_TEMPLATE;
         }
     };
 
     /**
      * Object returned when there is an unparcelling error.
+     * @hide
      */
-    public static final @NonNull ControlTemplate ERROR_TEMPLATE = new ControlTemplate("") {
+    private static final @NonNull ControlTemplate ERROR_TEMPLATE = new ControlTemplate("") {
         @Override
         public int getTemplateType() {
             return TYPE_ERROR;
@@ -73,10 +75,9 @@ public abstract class ControlTemplate {
     @Retention(RetentionPolicy.SOURCE)
     @IntDef({
             TYPE_ERROR,
-            TYPE_NONE,
+            TYPE_NO_TEMPLATE,
             TYPE_TOGGLE,
             TYPE_RANGE,
-            TYPE_THUMBNAIL,
             TYPE_TOGGLE_RANGE,
             TYPE_TEMPERATURE,
             TYPE_STATELESS
@@ -84,14 +85,14 @@ public abstract class ControlTemplate {
     public @interface TemplateType {}
 
     /**
-     * Type identifier of {@link #ERROR_TEMPLATE}.
+     * Type identifier of the template returned by {@link #getErrorTemplate()}.
      */
     public static final @TemplateType int TYPE_ERROR = -1;
 
     /**
-     * Type identifier of {@link ControlTemplate#NO_TEMPLATE}.
+     * Type identifier of {@link ControlTemplate#getNoTemplateObject}.
      */
-    public static final @TemplateType int TYPE_NONE = 0;
+    public static final @TemplateType int TYPE_NO_TEMPLATE = 0;
 
     /**
      * Type identifier of {@link ToggleTemplate}.
@@ -104,11 +105,6 @@ public abstract class ControlTemplate {
     public static final @TemplateType int TYPE_RANGE = 2;
 
     /**
-     * Type identifier of {@link ThumbnailTemplate}.
-     */
-    public static final @TemplateType int TYPE_THUMBNAIL = 3;
-
-    /**
      * Type identifier of {@link ToggleRangeTemplate}.
      */
     public static final @TemplateType int TYPE_TOGGLE_RANGE = 6;
@@ -191,15 +187,13 @@ public abstract class ControlTemplate {
                     return new ToggleTemplate(bundle);
                 case TYPE_RANGE:
                     return new RangeTemplate(bundle);
-                case TYPE_THUMBNAIL:
-                    return new ThumbnailTemplate(bundle);
                 case TYPE_TOGGLE_RANGE:
                     return new ToggleRangeTemplate(bundle);
                 case TYPE_TEMPERATURE:
                     return new TemperatureControlTemplate(bundle);
                 case TYPE_STATELESS:
                     return new StatelessTemplate(bundle);
-                case TYPE_NONE:
+                case TYPE_NO_TEMPLATE:
                     return NO_TEMPLATE;
                 case TYPE_ERROR:
                 default:
@@ -210,4 +204,27 @@ public abstract class ControlTemplate {
             return ERROR_TEMPLATE;
         }
     }
+
+    /**
+     * @return a singleton {@link ControlTemplate} used for indicating an error in unparceling.
+     */
+    @NonNull
+    public static ControlTemplate getErrorTemplate() {
+        return ERROR_TEMPLATE;
+    }
+
+    /**
+     * Get a singleton {@link ControlTemplate} that has no features.
+     *
+     * This template has no distinctive field, not even an identifier. Used for a {@link Control}
+     * that accepts no type of input, or when there is no known state.
+     *
+     * @return a singleton {@link ControlTemplate} to indicate no specific template is used by
+     *         this {@link Control}
+     */
+    @NonNull
+    public static ControlTemplate getNoTemplateObject() {
+        return NO_TEMPLATE;
+    }
+
 }
diff --git a/core/java/android/service/controls/templates/TemperatureControlTemplate.java b/core/java/android/service/controls/templates/TemperatureControlTemplate.java
index 0818c7e4fb82..96be97a5f3ee 100644
--- a/core/java/android/service/controls/templates/TemperatureControlTemplate.java
+++ b/core/java/android/service/controls/templates/TemperatureControlTemplate.java
@@ -60,16 +60,34 @@ public final class TemperatureControlTemplate extends ControlTemplate {
 
     private static final int NUM_MODES = 6;
 
+    /**
+     * Use when the current or active mode of the device is not known
+     */
     public static final @Mode int MODE_UNKNOWN = 0;
 
+    /**
+     * Indicates that the current or active mode of the device is off.
+     */
     public static final @Mode int MODE_OFF = 1;
 
+    /**
+     * Indicates that the current or active mode of the device is set to heat.
+     */
     public static final @Mode int MODE_HEAT = 2;
 
+    /**
+     * Indicates that the current or active mode of the device is set to cool.
+     */
     public static final @Mode int MODE_COOL = 3;
 
+    /**
+     * Indicates that the current or active mode of the device is set to heat-cool.
+     */
     public static final @Mode int MODE_HEAT_COOL = 4;
 
+    /**
+     * Indicates that the current or active mode of the device is set to eco.
+     */
     public static final @Mode int MODE_ECO = 5;
 
     /**
@@ -85,10 +103,29 @@ public final class TemperatureControlTemplate extends ControlTemplate {
     })
     public @interface ModeFlag {}
 
+    /**
+     * Flag to indicate that the device supports off mode.
+     */
     public static final int FLAG_MODE_OFF = 1 << MODE_OFF;
+
+    /**
+     * Flag to indicate that the device supports heat mode.
+     */
     public static final int FLAG_MODE_HEAT = 1 << MODE_HEAT;
+
+    /**
+     * Flag to indicate that the device supports cool mode.
+     */
     public static final int FLAG_MODE_COOL = 1 << MODE_COOL;
+
+    /**
+     * Flag to indicate that the device supports heat-cool mode.
+     */
     public static final int FLAG_MODE_HEAT_COOL = 1 << MODE_HEAT_COOL;
+
+    /**
+     * Flag to indicate that the device supports eco mode.
+     */
     public static final int FLAG_MODE_ECO = 1 << MODE_ECO;
     private static final int ALL_FLAGS =
             FLAG_MODE_OFF |
diff --git a/core/java/android/service/controls/templates/ThumbnailTemplate.java b/core/java/android/service/controls/templates/ThumbnailTemplate.java
deleted file mode 100644
index 72179f4edc5e..000000000000
--- a/core/java/android/service/controls/templates/ThumbnailTemplate.java
+++ /dev/null
@@ -1,98 +0,0 @@
-/*
- * Copyright (C) 2019 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.
- */
-
-package android.service.controls.templates;
-
-import android.annotation.NonNull;
-import android.graphics.drawable.Icon;
-import android.os.Bundle;
-import android.service.controls.Control;
-
-import com.android.internal.util.Preconditions;
-
-/**
- * A template for a {@link Control} that displays an image.
- */
-public final class ThumbnailTemplate extends ControlTemplate {
-
-    private static final @TemplateType int TYPE = TYPE_THUMBNAIL;
-    private static final String KEY_ICON = "key_icon";
-    private static final String KEY_CONTENT_DESCRIPTION = "key_content_description";
-
-    private final @NonNull Icon mThumbnail;
-    private final @NonNull CharSequence mContentDescription;
-
-    /**
-     * @param templateId the identifier for this template object
-     * @param thumbnail an image to display on the {@link Control}
-     * @param contentDescription a description of the image for accessibility.
-     */
-    public ThumbnailTemplate(@NonNull String templateId, @NonNull Icon thumbnail,
-            @NonNull CharSequence contentDescription) {
-        super(templateId);
-        Preconditions.checkNotNull(thumbnail);
-        Preconditions.checkNotNull(contentDescription);
-        mThumbnail = thumbnail;
-        mContentDescription = contentDescription;
-    }
-
-    /**
-     * @param b
-     * @hide
-     */
-    ThumbnailTemplate(Bundle b) {
-        super(b);
-        mThumbnail = b.getParcelable(KEY_ICON);
-        mContentDescription = b.getCharSequence(KEY_CONTENT_DESCRIPTION, "");
-    }
-
-    /**
-     * The {@link Icon} (image) displayed by this template.
-     */
-    @NonNull
-    public Icon getThumbnail() {
-        return mThumbnail;
-    }
-
-    /**
-     * The description of the image returned by {@link ThumbnailTemplate#getThumbnail()}
-     */
-    @NonNull
-    public CharSequence getContentDescription() {
-        return mContentDescription;
-    }
-
-    /**
-     * @return {@link ControlTemplate#TYPE_THUMBNAIL}
-     */
-    @Override
-    public int getTemplateType() {
-        return TYPE;
-    }
-
-    /**
-     * @return
-     * @hide
-     */
-    @Override
-    @NonNull
-    Bundle getDataBundle() {
-        Bundle b = super.getDataBundle();
-        b.putObject(KEY_ICON, mThumbnail);
-        b.putObject(KEY_CONTENT_DESCRIPTION, mContentDescription);
-        return b;
-    }
-}