Fix bug 2553592 API REVIEW: android.speech

Change 1 of 4
Notes from API Council review:
Rename RecognitionManager to SpeechRecognizer

Change-Id: I892c0d714d928d5e31575c72b6a36281fc4c7a8a

api/current.xml

@@ -138081,225 +138081,6 @@
 </parameter>
 </method>
 </interface>
-<class name="RecognitionManager"
- extends="java.lang.Object"
- abstract="false"
- static="false"
- final="false"
- deprecated="not deprecated"
- visibility="public"
->
-<method name="cancel"
- return="void"
- abstract="false"
- native="false"
- synchronized="false"
- static="false"
- final="false"
- deprecated="not deprecated"
- visibility="public"
->
-</method>
-<method name="createRecognitionManager"
- return="android.speech.RecognitionManager"
- abstract="false"
- native="false"
- synchronized="false"
- static="true"
- final="false"
- deprecated="not deprecated"
- visibility="public"
->
-<parameter name="context" type="android.content.Context">
-</parameter>
-</method>
-<method name="createRecognitionManager"
- return="android.speech.RecognitionManager"
- abstract="false"
- native="false"
- synchronized="false"
- static="true"
- final="false"
- deprecated="not deprecated"
- visibility="public"
->
-<parameter name="context" type="android.content.Context">
-</parameter>
-<parameter name="serviceComponent" type="android.content.ComponentName">
-</parameter>
-</method>
-<method name="destroy"
- return="void"
- abstract="false"
- native="false"
- synchronized="false"
- static="false"
- final="false"
- deprecated="not deprecated"
- visibility="public"
->
-</method>
-<method name="isRecognitionAvailable"
- return="boolean"
- abstract="false"
- native="false"
- synchronized="false"
- static="true"
- final="false"
- deprecated="not deprecated"
- visibility="public"
->
-<parameter name="context" type="android.content.Context">
-</parameter>
-</method>
-<method name="setRecognitionListener"
- return="void"
- abstract="false"
- native="false"
- synchronized="false"
- static="false"
- final="false"
- deprecated="not deprecated"
- visibility="public"
->
-<parameter name="listener" type="android.speech.RecognitionListener">
-</parameter>
-</method>
-<method name="startListening"
- return="void"
- abstract="false"
- native="false"
- synchronized="false"
- static="false"
- final="false"
- deprecated="not deprecated"
- visibility="public"
->
-<parameter name="recognizerIntent" type="android.content.Intent">
-</parameter>
-</method>
-<method name="stopListening"
- return="void"
- abstract="false"
- native="false"
- synchronized="false"
- static="false"
- final="false"
- deprecated="not deprecated"
- visibility="public"
->
-</method>
-<field name="ERROR_AUDIO"
- type="int"
- transient="false"
- volatile="false"
- value="3"
- static="true"
- final="true"
- deprecated="not deprecated"
- visibility="public"
->
-</field>
-<field name="ERROR_CLIENT"
- type="int"
- transient="false"
- volatile="false"
- value="5"
- static="true"
- final="true"
- deprecated="not deprecated"
- visibility="public"
->
-</field>
-<field name="ERROR_INSUFFICIENT_PERMISSIONS"
- type="int"
- transient="false"
- volatile="false"
- value="9"
- static="true"
- final="true"
- deprecated="not deprecated"
- visibility="public"
->
-</field>
-<field name="ERROR_NETWORK"
- type="int"
- transient="false"
- volatile="false"
- value="2"
- static="true"
- final="true"
- deprecated="not deprecated"
- visibility="public"
->
-</field>
-<field name="ERROR_NETWORK_TIMEOUT"
- type="int"
- transient="false"
- volatile="false"
- value="1"
- static="true"
- final="true"
- deprecated="not deprecated"
- visibility="public"
->
-</field>
-<field name="ERROR_NO_MATCH"
- type="int"
- transient="false"
- volatile="false"
- value="7"
- static="true"
- final="true"
- deprecated="not deprecated"
- visibility="public"
->
-</field>
-<field name="ERROR_RECOGNIZER_BUSY"
- type="int"
- transient="false"
- volatile="false"
- value="8"
- static="true"
- final="true"
- deprecated="not deprecated"
- visibility="public"
->
-</field>
-<field name="ERROR_SERVER"
- type="int"
- transient="false"
- volatile="false"
- value="4"
- static="true"
- final="true"
- deprecated="not deprecated"
- visibility="public"
->
-</field>
-<field name="ERROR_SPEECH_TIMEOUT"
- type="int"
- transient="false"
- volatile="false"
- value="6"
- static="true"
- final="true"
- deprecated="not deprecated"
- visibility="public"
->
-</field>
-<field name="RESULTS_RECOGNITION"
- type="java.lang.String"
- transient="false"
- volatile="false"
- value="&quot;results_recognition&quot;"
- static="true"
- final="true"
- deprecated="not deprecated"
- visibility="public"
->
-</field>
-</class>
 <class name="RecognitionService"
  extends="android.app.Service"
  abstract="true"
@@ -138826,6 +138607,225 @@
 >
 </field>
 </class>
+<class name="SpeechRecognizer"
+ extends="java.lang.Object"
+ abstract="false"
+ static="false"
+ final="false"
+ deprecated="not deprecated"
+ visibility="public"
+>
+<method name="cancel"
+ return="void"
+ abstract="false"
+ native="false"
+ synchronized="false"
+ static="false"
+ final="false"
+ deprecated="not deprecated"
+ visibility="public"
+>
+</method>
+<method name="createSpeechRecognizer"
+ return="android.speech.SpeechRecognizer"
+ abstract="false"
+ native="false"
+ synchronized="false"
+ static="true"
+ final="false"
+ deprecated="not deprecated"
+ visibility="public"
+>
+<parameter name="context" type="android.content.Context">
+</parameter>
+</method>
+<method name="createSpeechRecognizer"
+ return="android.speech.SpeechRecognizer"
+ abstract="false"
+ native="false"
+ synchronized="false"
+ static="true"
+ final="false"
+ deprecated="not deprecated"
+ visibility="public"
+>
+<parameter name="context" type="android.content.Context">
+</parameter>
+<parameter name="serviceComponent" type="android.content.ComponentName">
+</parameter>
+</method>
+<method name="destroy"
+ return="void"
+ abstract="false"
+ native="false"
+ synchronized="false"
+ static="false"
+ final="false"
+ deprecated="not deprecated"
+ visibility="public"
+>
+</method>
+<method name="isRecognitionAvailable"
+ return="boolean"
+ abstract="false"
+ native="false"
+ synchronized="false"
+ static="true"
+ final="false"
+ deprecated="not deprecated"
+ visibility="public"
+>
+<parameter name="context" type="android.content.Context">
+</parameter>
+</method>
+<method name="setRecognitionListener"
+ return="void"
+ abstract="false"
+ native="false"
+ synchronized="false"
+ static="false"
+ final="false"
+ deprecated="not deprecated"
+ visibility="public"
+>
+<parameter name="listener" type="android.speech.RecognitionListener">
+</parameter>
+</method>
+<method name="startListening"
+ return="void"
+ abstract="false"
+ native="false"
+ synchronized="false"
+ static="false"
+ final="false"
+ deprecated="not deprecated"
+ visibility="public"
+>
+<parameter name="recognizerIntent" type="android.content.Intent">
+</parameter>
+</method>
+<method name="stopListening"
+ return="void"
+ abstract="false"
+ native="false"
+ synchronized="false"
+ static="false"
+ final="false"
+ deprecated="not deprecated"
+ visibility="public"
+>
+</method>
+<field name="ERROR_AUDIO"
+ type="int"
+ transient="false"
+ volatile="false"
+ value="3"
+ static="true"
+ final="true"
+ deprecated="not deprecated"
+ visibility="public"
+>
+</field>
+<field name="ERROR_CLIENT"
+ type="int"
+ transient="false"
+ volatile="false"
+ value="5"
+ static="true"
+ final="true"
+ deprecated="not deprecated"
+ visibility="public"
+>
+</field>
+<field name="ERROR_INSUFFICIENT_PERMISSIONS"
+ type="int"
+ transient="false"
+ volatile="false"
+ value="9"
+ static="true"
+ final="true"
+ deprecated="not deprecated"
+ visibility="public"
+>
+</field>
+<field name="ERROR_NETWORK"
+ type="int"
+ transient="false"
+ volatile="false"
+ value="2"
+ static="true"
+ final="true"
+ deprecated="not deprecated"
+ visibility="public"
+>
+</field>
+<field name="ERROR_NETWORK_TIMEOUT"
+ type="int"
+ transient="false"
+ volatile="false"
+ value="1"
+ static="true"
+ final="true"
+ deprecated="not deprecated"
+ visibility="public"
+>
+</field>
+<field name="ERROR_NO_MATCH"
+ type="int"
+ transient="false"
+ volatile="false"
+ value="7"
+ static="true"
+ final="true"
+ deprecated="not deprecated"
+ visibility="public"
+>
+</field>
+<field name="ERROR_RECOGNIZER_BUSY"
+ type="int"
+ transient="false"
+ volatile="false"
+ value="8"
+ static="true"
+ final="true"
+ deprecated="not deprecated"
+ visibility="public"
+>
+</field>
+<field name="ERROR_SERVER"
+ type="int"
+ transient="false"
+ volatile="false"
+ value="4"
+ static="true"
+ final="true"
+ deprecated="not deprecated"
+ visibility="public"
+>
+</field>
+<field name="ERROR_SPEECH_TIMEOUT"
+ type="int"
+ transient="false"
+ volatile="false"
+ value="6"
+ static="true"
+ final="true"
+ deprecated="not deprecated"
+ visibility="public"
+>
+</field>
+<field name="RESULTS_RECOGNITION"
+ type="java.lang.String"
+ transient="false"
+ volatile="false"
+ value="&quot;results_recognition&quot;"
+ static="true"
+ final="true"
+ deprecated="not deprecated"
+ visibility="public"
+>
+</field>
+</class>
 </package>
 <package name="android.speech.tts"
 >

core/java/android/speech/IRecognitionListener.aidl

@@ -59,7 +59,7 @@ oneway interface IRecognitionListener {
     /**
      * A network or recognition error occurred.
      *
-     * @param error code is defined in {@link RecognitionManager}
+     * @param error code is defined in {@link SpeechRecognizer}
      */
     void onError(in int error);
 

core/java/android/speech/IRecognitionService.aidl

@@ -25,7 +25,7 @@ import android.speech.IRecognitionListener;
 * you want to begin capturing audio; RecognitionService will automatically
 * determine when the user has finished speaking, stream the audio to the
 * recognition servers, and notify you when results are ready. In most of the cases, 
-* this class should not be used directly, instead use {@link RecognitionManager} for
+* this class should not be used directly, instead use {@link SpeechRecognizer} for
 * accessing recognition service. 
 * {@hide}
 */

core/java/android/speech/RecognitionListener.java

@@ -19,7 +19,7 @@ import android.content.Intent;
 import android.os.Bundle;
 
 /**
- * Used for receiving notifications from the RecognitionManager when the
+ * Used for receiving notifications from the SpeechRecognizer when the
  * recognition related events occur. All the callbacks are executed on the
  * Application main thread.
  */
@@ -61,7 +61,7 @@ public interface RecognitionListener {
     /**
      * A network or recognition error occurred.
      * 
-     * @param error code is defined in {@link RecognitionManager}
+     * @param error code is defined in {@link SpeechRecognizer}
      */
     void onError(int error);
 
@@ -70,7 +70,7 @@ public interface RecognitionListener {
      * 
      * @param results the recognition results. To retrieve the results in {@code
      *        ArrayList<String>} format use {@link Bundle#getStringArrayList(String)} with
-     *        {@link RecognitionManager#RESULTS_RECOGNITION} as a parameter
+     *        {@link SpeechRecognizer#RESULTS_RECOGNITION} as a parameter
      */
     void onResults(Bundle results);
 
@@ -78,13 +78,13 @@ public interface RecognitionListener {
      * Called when partial recognition results are available. The callback might be called at any
      * time between {@link #onBeginningOfSpeech()} and {@link #onResults(Bundle)} when partial
      * results are ready. This method may be called zero, one or multiple times for each call to
-     * {@link RecognitionManager#startListening(Intent)}, depending on the speech recognition
+     * {@link SpeechRecognizer#startListening(Intent)}, depending on the speech recognition
      * service implementation.  To request partial results, use
      * {@link RecognizerIntent#EXTRA_PARTIAL_RESULTS}
      * 
      * @param partialResults the returned results. To retrieve the results in
      *        ArrayList<String> format use {@link Bundle#getStringArrayList(String)} with
-     *        {@link RecognitionManager#RESULTS_RECOGNITION} as a parameter
+     *        {@link SpeechRecognizer#RESULTS_RECOGNITION} as a parameter
      */
     void onPartialResults(Bundle partialResults);
 

core/java/android/speech/RecognitionService.java

@@ -89,7 +89,7 @@ public abstract class RecognitionService extends Service {
             RecognitionService.this.onStartListening(intent, mCurrentCallback);
         } else {
             try {
-                listener.onError(RecognitionManager.ERROR_RECOGNIZER_BUSY);
+                listener.onError(SpeechRecognizer.ERROR_RECOGNIZER_BUSY);
             } catch (RemoteException e) {
                 Log.d(TAG, "onError call from startListening failed");
             }
@@ -100,10 +100,10 @@ public abstract class RecognitionService extends Service {
     private void dispatchStopListening(IRecognitionListener listener) {
         try {
             if (mCurrentCallback == null) {
-                listener.onError(RecognitionManager.ERROR_CLIENT);
+                listener.onError(SpeechRecognizer.ERROR_CLIENT);
                 Log.w(TAG, "stopListening called with no preceding startListening - ignoring");
             } else if (mCurrentCallback.mListener.asBinder() != listener.asBinder()) {
-                listener.onError(RecognitionManager.ERROR_RECOGNIZER_BUSY);
+                listener.onError(SpeechRecognizer.ERROR_RECOGNIZER_BUSY);
                 Log.w(TAG, "stopListening called by other caller than startListening - ignoring");
             } else { // the correct state
                 RecognitionService.this.onStopListening(mCurrentCallback);
@@ -175,7 +175,7 @@ public abstract class RecognitionService extends Service {
         }
         try {
             Log.e(TAG, "call for recognition service without RECORD_AUDIO permissions");
-            listener.onError(RecognitionManager.ERROR_INSUFFICIENT_PERMISSIONS);
+            listener.onError(SpeechRecognizer.ERROR_INSUFFICIENT_PERMISSIONS);
         } catch (RemoteException re) {
             Log.e(TAG, "sending ERROR_INSUFFICIENT_PERMISSIONS message failed", re);
         }
@@ -252,7 +252,7 @@ public abstract class RecognitionService extends Service {
         /**
          * The service should call this method when a network or recognition error occurred.
          * 
-         * @param error code is defined in {@link RecognitionManager}
+         * @param error code is defined in {@link SpeechRecognizer}
          */
         public void error(int error) throws RemoteException {
             mCurrentCallback = null;
@@ -263,12 +263,12 @@ public abstract class RecognitionService extends Service {
          * The service should call this method when partial recognition results are available. This
          * method can be called at any time between {@link #beginningOfSpeech()} and
          * {@link #results(Bundle)} when partial results are ready. This method may be called zero,
-         * one or multiple times for each call to {@link RecognitionManager#startListening(Intent)},
+         * one or multiple times for each call to {@link SpeechRecognizer#startListening(Intent)},
          * depending on the speech recognition service implementation.
          * 
          * @param partialResults the returned results. To retrieve the results in
          *        ArrayList<String> format use {@link Bundle#getStringArrayList(String)} with
-         *        {@link RecognitionManager#RESULTS_RECOGNITION} as a parameter
+         *        {@link SpeechRecognizer#RESULTS_RECOGNITION} as a parameter
          */
         public void partialResults(Bundle partialResults) throws RemoteException {
             mListener.onPartialResults(partialResults);
@@ -289,7 +289,7 @@ public abstract class RecognitionService extends Service {
          * 
          * @param results the recognition results. To retrieve the results in {@code
          *        ArrayList<String>} format use {@link Bundle#getStringArrayList(String)} with
-         *        {@link RecognitionManager#RESULTS_RECOGNITION} as a parameter
+         *        {@link SpeechRecognizer#RESULTS_RECOGNITION} as a parameter
          */
         public void results(Bundle results) throws RemoteException {
             mCurrentCallback = null;

core/java/android/speech/SpeechRecognizer.java

@@ -38,16 +38,16 @@ import java.util.Queue;
 /**
  * This class provides access to the speech recognition service. This service allows access to the
  * speech recognizer. Do not instantiate this class directly, instead, call
- * {@link RecognitionManager#createRecognitionManager(Context)}. This class's methods must be
+ * {@link SpeechRecognizer#createSpeechRecognizer(Context)}. This class's methods must be
  * invoked only from the main application thread. Please note that the application must have
  * {@link android.Manifest.permission#RECORD_AUDIO} permission to use this class.
  */
-public class RecognitionManager {
+public class SpeechRecognizer {
     /** DEBUG value to enable verbose debug prints */
     private final static boolean DBG = false;
 
     /** Log messages identifier */
-    private static final String TAG = "RecognitionManager";
+    private static final String TAG = "SpeechRecognizer";
 
     /**
      * Used to retrieve an {@code ArrayList<String>} from the {@link Bundle} passed to the
@@ -133,10 +133,10 @@ public class RecognitionManager {
     private final InternalListener mListener = new InternalListener();
 
     /**
-     * The right way to create a {@code RecognitionManager} is by using
-     * {@link #createRecognitionManager} static factory method
+     * The right way to create a {@code SpeechRecognizer} is by using
+     * {@link #createSpeechRecognizer} static factory method
      */
-    private RecognitionManager(final Context context, final ComponentName serviceComponent) {
+    private SpeechRecognizer(final Context context, final ComponentName serviceComponent) {
         mContext = context;
         mServiceComponent = serviceComponent;
     }
@@ -167,10 +167,10 @@ public class RecognitionManager {
 
     /**
      * Checks whether a speech recognition service is available on the system. If this method
-     * returns {@code false}, {@link RecognitionManager#createRecognitionManager(Context)} will
+     * returns {@code false}, {@link SpeechRecognizer#createSpeechRecognizer(Context)} will
      * fail.
      * 
-     * @param context with which {@code RecognitionManager} will be created
+     * @param context with which {@code SpeechRecognizer} will be created
      * @return {@code true} if recognition is available, {@code false} otherwise
      */
     public static boolean isRecognitionAvailable(final Context context) {
@@ -180,41 +180,41 @@ public class RecognitionManager {
     }
 
     /**
-     * Factory method to create a new {@code RecognitionManager}. Please note that
+     * Factory method to create a new {@code SpeechRecognizer}. Please note that
      * {@link #setRecognitionListener(RecognitionListener)} should be called before dispatching any
-     * command to the created {@code RecognitionManager}, otherwise no notifications will be
+     * command to the created {@code SpeechRecognizer}, otherwise no notifications will be
      * received.
      *
-     * @param context in which to create {@code RecognitionManager}
-     * @return a new {@code RecognitionManager}
+     * @param context in which to create {@code SpeechRecognizer}
+     * @return a new {@code SpeechRecognizer}
      */
-    public static RecognitionManager createRecognitionManager(final Context context) {
-        return createRecognitionManager(context, null);
+    public static SpeechRecognizer createSpeechRecognizer(final Context context) {
+        return createSpeechRecognizer(context, null);
     }
 
     /**
-     * Factory method to create a new {@code RecognitionManager}. Please note that
+     * Factory method to create a new {@code SpeechRecognizer}. Please note that
      * {@link #setRecognitionListener(RecognitionListener)} should be called before dispatching any
-     * command to the created {@code RecognitionManager}, otherwise no notifications will be
+     * command to the created {@code SpeechRecognizer}, otherwise no notifications will be
      * received.
      *
      * Use this version of the method to specify a specific service to direct this
-     * {@link RecognitionManager} to. Normally you would not use this; use
-     * {@link #createRecognitionManager(Context)} instead to use the system default recognition
+     * {@link SpeechRecognizer} to. Normally you would not use this; use
+     * {@link #createSpeechRecognizer(Context)} instead to use the system default recognition
      * service.
      * 
-     * @param context in which to create {@code RecognitionManager}
+     * @param context in which to create {@code SpeechRecognizer}
      * @param serviceComponent the {@link ComponentName} of a specific service to direct this
-     *        {@code RecognitionManager} to
-     * @return a new {@code RecognitionManager}
+     *        {@code SpeechRecognizer} to
+     * @return a new {@code SpeechRecognizer}
      */
-    public static RecognitionManager createRecognitionManager(final Context context,
+    public static SpeechRecognizer createSpeechRecognizer(final Context context,
             final ComponentName serviceComponent) {
         if (context == null) {
             throw new IllegalArgumentException("Context cannot be null)");
         }
         checkIsCalledFromMainThread();
-        return new RecognitionManager(context, serviceComponent);
+        return new SpeechRecognizer(context, serviceComponent);
     }
 
     /**
@@ -223,7 +223,7 @@ public class RecognitionManager {
      * listener.
      * 
      * @param listener listener that will receive all the callbacks from the created
-     *        {@link RecognitionManager}, this must not be null.
+     *        {@link SpeechRecognizer}, this must not be null.
      */
     public void setRecognitionListener(RecognitionListener listener) {
         checkIsCalledFromMainThread();
@@ -303,7 +303,7 @@ public class RecognitionManager {
     private static void checkIsCalledFromMainThread() {
         if (Looper.myLooper() != Looper.getMainLooper()) {
             throw new RuntimeException(
-                    "RecognitionManager should be used only from the application's main thread");
+                    "SpeechRecognizer should be used only from the application's main thread");
         }
     }
 
@@ -373,7 +373,7 @@ public class RecognitionManager {
     }
 
     /**
-     * Destroys the {@code RecognitionManager} object.
+     * Destroys the {@code SpeechRecognizer} object.
      */
     public void destroy() {
         if (mConnection != null) {