chore: Deprecate touch actions (#1569)

Author: mykola-mokhnach

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

@@ -22,6 +22,18 @@
 import java.util.List;
 import java.util.Map;
 
+/**
+ * Touch actions are deprecated.
+ * Please use W3C Actions instead or the corresponding
+ * extension methods for the driver (if available).
+ * Check
+ * - https://www.youtube.com/watch?v=oAJ7jwMNFVU
+ * - https://appiumpro.com/editions/30-ios-specific-touch-action-methods
+ * - https://appiumpro.com/editions/29-automating-complex-gestures-with-the-w3c-actions-api
+ * for more details.
+ */
+@Deprecated
+@SuppressWarnings({"unchecked", "rawtypes"})
 public interface PerformsTouchActions extends ExecutesMethod {
     /**
      * Performs a chain of touch actions, which together can be considered an
@@ -36,6 +48,7 @@ public interface PerformsTouchActions extends ExecutesMethod {
      *                    touch actions to perform
      * @return the same touch action object
      */
+    @Deprecated
     default TouchAction performTouchAction(TouchAction touchAction) {
         Map<String, List<Object>> parameters = touchAction.getParameters();
         execute(PERFORM_TOUCH_ACTION, parameters);
@@ -53,9 +66,10 @@ default TouchAction performTouchAction(TouchAction touchAction) {
      *
      * @param multiAction the MultiTouchAction object to perform.
      */
-    default void performMultiTouchAction(MultiTouchAction multiAction) {
+    @Deprecated
+    default MultiTouchAction performMultiTouchAction(MultiTouchAction multiAction) {
         Map<String, List<Object>> parameters = multiAction.getParameters();
         execute(PERFORM_MULTI_TOUCH, parameters);
-        multiAction.clearActions();
+        return multiAction.clearActions();
     }
 }

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

@@ -42,7 +42,17 @@
  * action.press(element).waitAction(300).moveTo(element1).release().perform();
  * Calling perform() sends the action command to the Mobile Driver. Otherwise,
  * more and more actions can be chained.
+ *
+ * Touch actions are deprecated.
+ * Please use W3C Actions instead or the corresponding
+ * extension methods for the driver (if available).
+ * Check
+ * - https://www.youtube.com/watch?v=oAJ7jwMNFVU
+ * - https://appiumpro.com/editions/30-ios-specific-touch-action-methods
+ * - https://appiumpro.com/editions/29-automating-complex-gestures-with-the-w3c-actions-api
+ * for more details.
  */
+@Deprecated
 public class TouchAction<T extends TouchAction<T>> implements PerformsActions<T> {
 
     protected ImmutableList.Builder<ActionParameter> parameterBuilder;

src/main/java/io/appium/java_client/android/AndroidTouchAction.java

@@ -20,6 +20,17 @@
 import io.appium.java_client.TouchAction;
 
 
+/**
+ * Touch actions are deprecated.
+ * Please use W3C Actions instead or the corresponding
+ * extension methods for the driver (if available).
+ * Check
+ * - https://www.youtube.com/watch?v=oAJ7jwMNFVU
+ * - https://appiumpro.com/editions/30-ios-specific-touch-action-methods
+ * - https://appiumpro.com/editions/29-automating-complex-gestures-with-the-w3c-actions-api
+ * for more details.
+ */
+@Deprecated
 public class AndroidTouchAction extends TouchAction<AndroidTouchAction> {
 
     public AndroidTouchAction(PerformsTouchActions performsTouchActions) {

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

@@ -54,7 +54,6 @@
 
 /**
  * iOS driver implementation.
- *
  */
 public class IOSDriver extends AppiumDriver implements
         SupportsContextSwitching,

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

@@ -22,6 +22,17 @@
 import io.appium.java_client.touch.offset.ElementOption;
 import io.appium.java_client.touch.offset.PointOption;
 
+/**
+ * Touch actions are deprecated.
+ * Please use W3C Actions instead or the corresponding
+ * extension methods for the driver (if available).
+ * Check
+ * - https://www.youtube.com/watch?v=oAJ7jwMNFVU
+ * - https://appiumpro.com/editions/30-ios-specific-touch-action-methods
+ * - https://appiumpro.com/editions/29-automating-complex-gestures-with-the-w3c-actions-api
+ * for more details.
+ */
+@Deprecated
 public class IOSTouchAction extends TouchAction<IOSTouchAction> {
 
     public IOSTouchAction(PerformsTouchActions performsTouchActions) {

src/main/java/io/appium/java_client/mac/Mac2Driver.java

@@ -17,6 +17,7 @@
 package io.appium.java_client.mac;
 
 import io.appium.java_client.AppiumDriver;
+import io.appium.java_client.PerformsTouchActions;
 import io.appium.java_client.remote.AutomationName;
 import io.appium.java_client.screenrecording.CanRecordScreen;
 import io.appium.java_client.service.local.AppiumDriverLocalService;
@@ -38,6 +39,7 @@
  * @since Appium 1.20.0
  */
 public class Mac2Driver extends AppiumDriver implements
+        PerformsTouchActions,
         CanRecordScreen {
     private static final String PLATFORM_NAME = Platform.MAC.name();
     private static final String AUTOMATION_NAME = AutomationName.MAC2;

src/main/java/io/appium/java_client/windows/WindowsDriver.java

@@ -18,6 +18,7 @@
 
 import io.appium.java_client.AppiumDriver;
 import io.appium.java_client.HidesKeyboardWithKeyName;
+import io.appium.java_client.PerformsTouchActions;
 import io.appium.java_client.remote.AutomationName;
 import io.appium.java_client.screenrecording.CanRecordScreen;
 import io.appium.java_client.service.local.AppiumDriverLocalService;
@@ -30,6 +31,7 @@
 import java.net.URL;
 
 public class WindowsDriver extends AppiumDriver implements
+        PerformsTouchActions,
         PressesKeyCode,
         HidesKeyboardWithKeyName,
         CanRecordScreen {