From e14a11c1dfc288237dc4b684d414ff62e06ddd02 Mon Sep 17 00:00:00 2001
From: Yohei Yukawa <yukawa@google.com>
Date: Fri, 23 Jul 2021 11:03:08 -0700
Subject: [PATCH] Clarify on DEFAULT_INPUT_METHOD and InputMethodInfo#getId()

This CL aims to clarify more on what "IME ID" means in Android.

"IME ID" is a string representation of a certain implementation of
InputMethodService, which has always been computed by

  new ComponentName(packageName, serviceName).flattenToShortString(),

then has been exposed to developers through at least the following two
public APIs.

 * Settings.Secure.DEFAULT_INPUT_METHOD
 * InputMethodInfo#getId()

Now that our IME CTS tests are already requiring that "IME ID" equals
to test IMEs' component name indirectly, it would be more beneficial
if we clearly mention that "IME ID" is guaranteed to be constructed by

  ComponentName#flattenToShortString()

hence is also guaranteed to be parsed with

  ComponentName#unflattenFromString().

It is to late to change strong representations that have been
exposed to developers for more than 10 years anyway.

Other than updating public API documents, this CL does nothing.

Fix: 192392438
Test: presubmit
Change-Id: I013cd79b92363fe6e438f445606b5fc53e2660f6
---
 core/java/android/provider/Settings.java              | 11 +++++++++--
 .../android/view/inputmethod/InputMethodInfo.java     |  5 +++--
 2 files changed, 12 insertions(+), 4 deletions(-)

diff --git a/core/java/android/provider/Settings.java b/core/java/android/provider/Settings.java
index 7376ac55238c2..d824226a3270e 100644
--- a/core/java/android/provider/Settings.java
+++ b/core/java/android/provider/Settings.java
@@ -6410,8 +6410,15 @@ public final class Settings {
         public static final String DATA_ROAMING = Global.DATA_ROAMING;
 
         /**
-         * Setting to record the input method used by default, holding the ID
-         * of the desired method.
+         * Stores {@link android.view.inputmethod.InputMethodInfo#getId()} of the input method
+         * service that is currently selected.
+         *
+         * <p>Although the name {@link #DEFAULT_INPUT_METHOD} implies that there is a concept of
+         * <i>default</i> input method, in reality this setting is no more or less than the
+         * <strong>currently selected</strong> input method. This setting can be updated at any
+         * time as a result of user-initiated and system-initiated input method switching.</p>
+         *
+         * <p>Use {@link ComponentName#unflattenFromString(String)} to parse the stored value.</p>
          */
         @Readable
         public static final String DEFAULT_INPUT_METHOD = "default_input_method";
diff --git a/core/java/android/view/inputmethod/InputMethodInfo.java b/core/java/android/view/inputmethod/InputMethodInfo.java
index 9b463bb9538fd..96198c64fa565 100644
--- a/core/java/android/view/inputmethod/InputMethodInfo.java
+++ b/core/java/android/view/inputmethod/InputMethodInfo.java
@@ -418,8 +418,9 @@ public final class InputMethodInfo implements Parcelable {
     }
 
     /**
-     * Return a unique ID for this input method.  The ID is generated from
-     * the package and class name implementing the method.
+     * @return a unique ID for this input method, which is guaranteed to be the same as the result
+     *         of {@code getComponent().flattenToShortString()}.
+     * @see ComponentName#unflattenFromString(String)
      */
     public String getId() {
         return mId;