refactor: Finish replacing iOS extensions with their mobile alternatives

src/main/java/io/appium/java_client/LocksDevice.java

@@ -16,8 +16,12 @@
 
 package io.appium.java_client;
 
+import com.google.common.collect.ImmutableMap;
+import org.openqa.selenium.UnsupportedCommandException;
+
 import java.time.Duration;
 
+import static com.google.common.base.Preconditions.checkNotNull;
 import static io.appium.java_client.MobileCommand.getIsDeviceLockedCommand;
 import static io.appium.java_client.MobileCommand.lockDeviceCommand;
 import static io.appium.java_client.MobileCommand.unlockDeviceCommand;
@@ -41,15 +45,31 @@ default void lockDevice() {
      *                 A negative/zero value will lock the device and return immediately.
      */
     default void lockDevice(Duration duration) {
-        CommandExecutionHelper.execute(this, lockDeviceCommand(duration));
+        try {
+            CommandExecutionHelper.executeScript(this, "mobile: lock", ImmutableMap.of(
+                    "seconds", duration.getSeconds()
+            ));
+        } catch (UnsupportedCommandException e) {
+            // TODO: Remove the fallback
+            CommandExecutionHelper.execute(this, lockDeviceCommand(duration));
+        }
     }
 
     /**
      * Unlock the device if it is locked. This method will return silently if the device
      * is not locked.
      */
     default void unlockDevice() {
-        CommandExecutionHelper.execute(this, unlockDeviceCommand());
+        try {
+            //noinspection ConstantConditions
+            if (!(Boolean) CommandExecutionHelper.executeScript(this, "mobile: isLocked")) {
+                return;
+            }
+            CommandExecutionHelper.executeScript(this, "mobile: unlock");
+        } catch (UnsupportedCommandException e) {
+            // TODO: Remove the fallback
+            CommandExecutionHelper.execute(this, unlockDeviceCommand());
+        }
     }
 
     /**
@@ -58,6 +78,13 @@ default void unlockDevice() {
      * @return true if the device is locked or false otherwise.
      */
     default boolean isDeviceLocked() {
-        return CommandExecutionHelper.execute(this, getIsDeviceLockedCommand());
+        try {
+            return checkNotNull(
+                    CommandExecutionHelper.executeScript(this, "mobile: isLocked")
+            );
+        } catch (UnsupportedCommandException e) {
+            // TODO: Remove the fallback
+            return checkNotNull(CommandExecutionHelper.execute(this, getIsDeviceLockedCommand()));
+        }
     }
 }

src/main/java/io/appium/java_client/MobileCommand.java

@@ -35,7 +35,6 @@
 /**
  * The repository of mobile commands defined in the Mobile JSON
  * wire protocol.
- *
  * Most of these commands are platform-specific obsolete things and should eventually be replaced with
  * calls to corresponding `mobile:` extensions, so we don't abuse non-w3c APIs
  */
@@ -383,7 +382,9 @@ public static AppiumCommandInfo deleteC(String url) {
      * @param keyName The button pressed by the mobile driver to attempt hiding the
      *                keyboard.
      * @return a key-value pair. The key is the command name. The value is a {@link Map} command arguments.
+     * @deprecated This helper is deprecated and will be removed in future versions.
      */
+    @Deprecated
     public static Map.Entry<String, Map<String, ?>> hideKeyboardCommand(String keyName) {
         return new AbstractMap.SimpleEntry<>(
                 HIDE_KEYBOARD, prepareArguments("keyName", keyName));
@@ -396,7 +397,9 @@ public static AppiumCommandInfo deleteC(String url) {
      * @param keyName  a String, representing the text displayed on the button of the
      *                 keyboard you want to press. For example: "Done".
      * @return a key-value pair. The key is the command name. The value is a {@link Map} command arguments.
+     * @deprecated This helper is deprecated and will be removed in future versions.
      */
+    @Deprecated
     public static Map.Entry<String, Map<String, ?>> hideKeyboardCommand(String strategy,
                                                                         String keyName) {
         String[] parameters = new String[]{"strategy", "key"};
@@ -442,7 +445,9 @@ public static ImmutableMap<String, Object> prepareArguments(String[] params,
      *
      * @param key code for the key pressed on the device.
      * @return a key-value pair. The key is the command name. The value is a {@link Map} command arguments.
+     * @deprecated This helper is deprecated and will be removed in future versions.
      */
+    @Deprecated
     public static Map.Entry<String, Map<String, ?>> pressKeyCodeCommand(int key) {
         return new AbstractMap.SimpleEntry<>(
                 PRESS_KEY_CODE, prepareArguments("keycode", key));
@@ -454,7 +459,9 @@ public static ImmutableMap<String, Object> prepareArguments(String[] params,
      * @param key       code for the key pressed on the Android device.
      * @param metastate metastate for the keypress.
      * @return a key-value pair. The key is the command name. The value is a {@link Map} command arguments.
+     * @deprecated This helper is deprecated and will be removed in future versions.
      */
+    @Deprecated
     public static Map.Entry<String, Map<String, ?>> pressKeyCodeCommand(int key,
                                                                         Integer metastate) {
         String[] parameters = new String[]{"keycode", "metastate"};
@@ -468,7 +475,9 @@ public static ImmutableMap<String, Object> prepareArguments(String[] params,
      *
      * @param key code for the long key pressed on the device.
      * @return a key-value pair. The key is the command name. The value is a {@link Map} command arguments.
+     * @deprecated This helper is deprecated and will be removed in future versions.
      */
+    @Deprecated
     public static Map.Entry<String, Map<String, ?>> longPressKeyCodeCommand(int key) {
         return new AbstractMap.SimpleEntry<>(
                 LONG_PRESS_KEY_CODE, prepareArguments("keycode", key));
@@ -480,7 +489,9 @@ public static ImmutableMap<String, Object> prepareArguments(String[] params,
      * @param key       code for the long key pressed on the Android device.
      * @param metastate metastate for the long key press.
      * @return a key-value pair. The key is the command name. The value is a {@link Map} command arguments.
+     * @deprecated This helper is deprecated and will be removed in future versions.
      */
+    @Deprecated
     public static Map.Entry<String, Map<String, ?>> longPressKeyCodeCommand(int key,
                                                                             Integer metastate) {
         String[] parameters = new String[]{"keycode", "metastate"};
@@ -494,7 +505,9 @@ public static ImmutableMap<String, Object> prepareArguments(String[] params,
      *
      * @param duration for how long to lock the screen for. Minimum time resolution is one second
      * @return a key-value pair. The key is the command name. The value is a {@link Map} command arguments.
+     * @deprecated This helper is deprecated and will be removed in future versions.
      */
+    @Deprecated
     public static Map.Entry<String, Map<String, ?>> lockDeviceCommand(Duration duration) {
         return new AbstractMap.SimpleEntry<>(
                 LOCK, prepareArguments("seconds", duration.getSeconds()));
@@ -504,7 +517,9 @@ public static ImmutableMap<String, Object> prepareArguments(String[] params,
      * This method forms a {@link Map} of parameters for the device unlocking.
      *
      * @return a key-value pair. The key is the command name. The value is a {@link Map} command arguments.
+     * @deprecated This helper is deprecated and will be removed in future versions.
      */
+    @Deprecated
     public static Map.Entry<String, Map<String, ?>> unlockDeviceCommand() {
         return new AbstractMap.SimpleEntry<>(UNLOCK, ImmutableMap.of());
     }
@@ -513,7 +528,9 @@ public static ImmutableMap<String, Object> prepareArguments(String[] params,
      * This method forms a {@link Map} of parameters for the device locked query.
      *
      * @return a key-value pair. The key is the command name. The value is a {@link Map} command arguments.
+     * @deprecated This helper is deprecated and will be removed in future versions.
      */
+    @Deprecated
     public static Map.Entry<String, Map<String, ?>> getIsDeviceLockedCommand() {
         return new AbstractMap.SimpleEntry<>(IS_LOCKED, ImmutableMap.of());
     }
@@ -536,7 +553,9 @@ public static ImmutableMap<String, Object> prepareArguments(String[] params,
      * @param remotePath Path to file to write data to on remote device
      * @param base64Data Base64 encoded byte array of data to write to remote device
      * @return a key-value pair. The key is the command name. The value is a {@link Map} command arguments.
+     * @deprecated This helper is deprecated and will be removed in future versions.
      */
+    @Deprecated
     public static Map.Entry<String, Map<String, ?>> pushFileCommand(String remotePath, byte[] base64Data) {
         String[] parameters = new String[]{"path", "data"};
         Object[] values = new Object[]{remotePath, new String(base64Data, StandardCharsets.UTF_8)};
@@ -580,7 +599,9 @@ public static ImmutableMap<String, Object> prepareArguments(String[] params,
      * This method forms a {@link Map} of parameters for the checking of the keyboard state (is it shown or not).
      *
      * @return a key-value pair. The key is the command name. The value is a {@link Map} command arguments.
+     * @deprecated This helper is deprecated and will be removed in future versions.
      */
+    @Deprecated
     public static Map.Entry<String, Map<String, ?>> isKeyboardShownCommand() {
         return new AbstractMap.SimpleEntry<>(IS_KEYBOARD_SHOWN, ImmutableMap.of());
     }

src/main/java/io/appium/java_client/ios/IOSMobileCommandHelper.java

@@ -22,23 +22,28 @@
 import java.util.AbstractMap;
 import java.util.Map;
 
+@Deprecated
 public class IOSMobileCommandHelper extends MobileCommand {
 
     /**
      * This method forms a {@link Map} of parameters for the device shaking.
      *
      * @return a key-value pair. The key is the command name. The value is a {@link Map} command arguments.
+     * @deprecated this helper is deprecated and will be removed in future versions.
      */
+    @Deprecated
     public static Map.Entry<String, Map<String, ?>>  shakeCommand() {
         return new AbstractMap.SimpleEntry<>(SHAKE, ImmutableMap.of());
     }
-    
+
     /**
      * This method forms a {@link Map} of parameters for the touchId simulator.
-     * 
+     *
      * @param match If true, simulates a successful fingerprint scan. If false, simulates a failed fingerprint scan.
      * @return a key-value pair. The key is the command name. The value is a {@link Map} command arguments.
+     * @deprecated this helper is deprecated and will be removed in future versions.
      */
+    @Deprecated
     public static Map.Entry<String, Map<String, ?>> touchIdCommand(boolean match) {
         return new AbstractMap.SimpleEntry<>(
             TOUCH_ID, prepareArguments("match", match));
@@ -50,7 +55,9 @@ public class IOSMobileCommandHelper extends MobileCommand {
      *
      * @param enabled Whether to enable or disable Touch ID Enrollment for Simulator.
      * @return a key-value pair. The key is the command name. The value is a {@link Map} command arguments.
+     * @deprecated this helper is deprecated and will be removed in future versions.
      */
+    @Deprecated
     public static Map.Entry<String, Map<String, ?>> toggleTouchIdEnrollmentCommand(boolean enabled) {
         return new AbstractMap.SimpleEntry<>(
                 TOUCH_ID_ENROLLMENT, prepareArguments("enabled", enabled));

src/main/java/io/appium/java_client/ios/PerformsTouchID.java

@@ -16,34 +16,36 @@
 
 package io.appium.java_client.ios;
 
+import com.google.common.collect.ImmutableMap;
 import io.appium.java_client.CommandExecutionHelper;
 import io.appium.java_client.ExecutesMethod;
 
-import static io.appium.java_client.ios.IOSMobileCommandHelper.toggleTouchIdEnrollmentCommand;
-import static io.appium.java_client.ios.IOSMobileCommandHelper.touchIdCommand;
-
 public interface PerformsTouchID extends ExecutesMethod {
 
     /**
-     * Simulate touchId event.
+     * Simulate touchId event on iOS Simulator. Check the documentation on 'mobile: sendBiometricMatch'
+     * extension for more details.
      *
      * @param match If true, simulates a successful fingerprint scan. If false, simulates a failed fingerprint scan.
      */
     default void performTouchID(boolean match) {
-        CommandExecutionHelper.execute(this, touchIdCommand(match));
+        CommandExecutionHelper.executeScript(this, "mobile: sendBiometricMatch", ImmutableMap.of(
+                "type", "touchId",
+                "match", match
+        ));
     }
 
     /**
-     * Enrolls touchId in iOS Simulators. This call will only work if Appium process or its
-     * parent application (e.g. Terminal.app or Appium.app) has
-     * access to Mac OS accessibility in System Preferences >
-     * Security & Privacy > Privacy > Accessibility list.
+     * Enrolls touchId in iOS Simulator. Check the documentation on 'mobile: enrollBiometric'
+     * extension for more details.
      *
      * @param enabled Whether to enable or disable Touch ID Enrollment. The actual state of the feature
      *                will only be changed if the current value is different from the previous one.
      *                Multiple calls of the method with the same argument value have no effect.
      */
     default void toggleTouchIDEnrollment(boolean enabled) {
-        CommandExecutionHelper.execute(this, toggleTouchIdEnrollmentCommand(enabled));
+        CommandExecutionHelper.executeScript(this, "mobile: enrollBiometric", ImmutableMap.of(
+                "isEnabled", enabled
+        ));
     }
 }

src/main/java/io/appium/java_client/ios/ShakesDevice.java

@@ -18,15 +18,21 @@
 
 import io.appium.java_client.CommandExecutionHelper;
 import io.appium.java_client.ExecutesMethod;
+import org.openqa.selenium.UnsupportedCommandException;
 
 import static io.appium.java_client.ios.IOSMobileCommandHelper.shakeCommand;
 
 public interface ShakesDevice extends ExecutesMethod {
 
     /**
-     * Simulate shaking the device.
+     * Simulate shaking the Simulator. This API does not work for real devices.
      */
     default void shake() {
-        CommandExecutionHelper.execute(this, shakeCommand());
+        try {
+            CommandExecutionHelper.executeScript(this, "mobile: shake");
+        } catch (UnsupportedCommandException e) {
+            // TODO: Remove the fallback
+            CommandExecutionHelper.execute(this, shakeCommand());
+        }
     }
 }