chore: Deprecate legacy app management helpers (#1571)

Author: mykola-mokhnach

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

@@ -17,13 +17,10 @@
 package io.appium.java_client;
 
 import static io.appium.java_client.MobileCommand.ACTIVATE_APP;
-import static io.appium.java_client.MobileCommand.CLOSE_APP;
 import static io.appium.java_client.MobileCommand.INSTALL_APP;
 import static io.appium.java_client.MobileCommand.IS_APP_INSTALLED;
-import static io.appium.java_client.MobileCommand.LAUNCH_APP;
 import static io.appium.java_client.MobileCommand.QUERY_APP_STATE;
 import static io.appium.java_client.MobileCommand.REMOVE_APP;
-import static io.appium.java_client.MobileCommand.RESET;
 import static io.appium.java_client.MobileCommand.RUN_APP_IN_BACKGROUND;
 import static io.appium.java_client.MobileCommand.TERMINATE_APP;
 import static io.appium.java_client.MobileCommand.prepareArguments;
@@ -40,16 +37,9 @@
 import java.util.AbstractMap;
 import javax.annotation.Nullable;
 
+@SuppressWarnings("rawtypes")
 public interface InteractsWithApps extends ExecutesMethod {
 
-    /**
-     * Launches the app, which was provided in the capabilities at session creation,
-     * and (re)starts the session.
-     */
-    default void launchApp() {
-        execute(LAUNCH_APP);
-    }
-
     /**
      * Install an app on the mobile device.
      *
@@ -63,7 +53,7 @@ default void installApp(String appPath) {
      * Install an app on the mobile device.
      *
      * @param appPath path to app to install or a remote URL.
-     * @param options Set of the corresponding instllation options for
+     * @param options Set of the corresponding installation options for
      *                the particular platform.
      */
     default void installApp(String appPath, @Nullable BaseInstallApplicationOptions options) {
@@ -86,13 +76,6 @@ default boolean isAppInstalled(String bundleId) {
                 new AbstractMap.SimpleEntry<>(IS_APP_INSTALLED, prepareArguments("bundleId", bundleId)));
     }
 
-    /**
-     * Resets the currently running app together with the session.
-     */
-    default void resetApp() {
-        execute(RESET);
-    }
-
     /**
      * Runs the current app as a background app for the time
      * requested. This is a synchronous method, it blocks while the
@@ -132,14 +115,6 @@ default boolean removeApp(String bundleId, @Nullable BaseRemoveApplicationOption
                 new AbstractMap.SimpleEntry<>(REMOVE_APP, prepareArguments(parameters, values)));
     }
 
-    /**
-     * Close the app which was provided in the capabilities at session creation
-     * and quits the session.
-     */
-    default void closeApp() {
-        execute(CLOSE_APP);
-    }
-
     /**
      * Activates the given app if it installed, but not running or if it is running in the
      * background.

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

@@ -47,8 +47,8 @@ public class MobileCommand {
     public static final String RUN_APP_IN_BACKGROUND;
     protected static final String PERFORM_TOUCH_ACTION;
     protected static final String PERFORM_MULTI_TOUCH;
-    protected static final String LAUNCH_APP;
-    protected static final String CLOSE_APP;
+    public static final String LAUNCH_APP;
+    public static final String CLOSE_APP;
     protected static final String GET_DEVICE_TIME;
     protected static final String GET_SESSION;
     protected static final String LOG_EVENT;

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

@@ -65,6 +65,7 @@ default TouchAction performTouchAction(TouchAction touchAction) {
      * is called.
      *
      * @param multiAction the MultiTouchAction object to perform.
+     * @return MultiTouchAction instance for chaining.
      */
     @Deprecated
     default MultiTouchAction performMultiTouchAction(MultiTouchAction multiAction) {

src/main/java/io/appium/java_client/InteractsWithFiles.java renamed to src/main/java/io/appium/java_client/PullsFiles.java

@@ -26,57 +26,41 @@
 import java.nio.charset.StandardCharsets;
 import java.util.Base64;
 
-public interface InteractsWithFiles extends ExecutesMethod {
+public interface PullsFiles extends ExecutesMethod {
 
     /**
-     * Pull a file from the simulator/device.
-     * On iOS the server should have ifuse
-     * libraries installed and configured properly for this feature to work
-     * on real devices.
+     * Pull a file from the remote system.
      * On Android the application under test should be
      * built with debuggable flag enabled in order to get access to its container
      * on the internal file system.
      *
-     * @see <a href="https://github.com/libimobiledevice/ifuse">iFuse GitHub page6</a>
-     * @see <a href="https://github.com/osxfuse/osxfuse/wiki/FAQ">osxFuse FAQ</a>
-     * @see <a href="https://developer.android.com/studio/debug/">'Debug Your App' developer article</a>
-     *
      * @param remotePath If the path starts with <em>@applicationId/</em>/ prefix, then the file
      *                   will be pulled from the root of the corresponding application container.
-     *                   Otherwise the root folder is considered as / on Android and
+     *                   Otherwise, the root folder is considered as / on Android and
      *                   on iOS it is a media folder root (real devices only).
      * @return A byte array of Base64 encoded data.
      */
     default byte[] pullFile(String remotePath) {
         Response response = execute(PULL_FILE, ImmutableMap.of("path", remotePath));
         String base64String = response.getValue().toString();
-
         return Base64.getDecoder().decode(base64String.getBytes(StandardCharsets.UTF_8));
     }
 
     /**
-     * Pull a folder content from the simulator/device.
-     * On iOS the server should have ifuse
-     * libraries installed and configured properly for this feature to work
-     * on real devices.
+     * Pull a folder content from the remote system.
      * On Android the application under test should be
      * built with debuggable flag enabled in order to get access to its container
      * on the internal file system.
      *
-     * @see <a href="https://github.com/libimobiledevice/ifuse">iFuse GitHub page6</a>
-     * @see <a href="https://github.com/osxfuse/osxfuse/wiki/FAQ">osxFuse FAQ</a>
-     * @see <a href="https://developer.android.com/studio/debug/">'Debug Your App' developer article</a>
-     *
      * @param remotePath If the path starts with <em>@applicationId/</em> prefix, then the folder
      *                   will be pulled from the root of the corresponding application container.
-     *                   Otherwise the root folder is considered as / on Android and
+     *                   Otherwise, the root folder is considered as / on Android and
      *                   on iOS it is a media folder root (real devices only).
      * @return A byte array of Base64 encoded zip archive data.
      */
     default byte[] pullFolder(String remotePath) {
         Response response = execute(PULL_FOLDER, ImmutableMap.of("path", remotePath));
         String base64String = response.getValue().toString();
-
         return Base64.getDecoder().decode(base64String.getBytes(StandardCharsets.UTF_8));
     }
 

src/main/java/io/appium/java_client/ios/PushesFiles.java renamed to src/main/java/io/appium/java_client/PushesFiles.java

@@ -14,13 +14,11 @@
  * limitations under the License.
  */
 
-package io.appium.java_client.ios;
+package io.appium.java_client;
 
 import static com.google.common.base.Preconditions.checkNotNull;
 import static io.appium.java_client.MobileCommand.pushFileCommand;
 
-import io.appium.java_client.CommandExecutionHelper;
-import io.appium.java_client.ExecutesMethod;
 import org.apache.commons.codec.binary.Base64;
 import org.apache.commons.io.FileUtils;
 
@@ -30,13 +28,7 @@
 public interface PushesFiles extends ExecutesMethod {
 
     /**
-     * Saves base64 encoded data as a media file on the remote mobile device.
-     * The server should have ifuse
-     * libraries installed and configured properly for this feature to work
-     * on real devices.
-     *
-     * @see <a href="https://github.com/libimobiledevice/ifuse">iFuse GitHub page</a>
-     * @see <a href="https://github.com/osxfuse/osxfuse/wiki/FAQ">osxFuse FAQ</a>
+     * Saves base64 encoded data as a media file on the remote system.
      *
      * @param remotePath Path to file to write data to on remote device
      *                   Only the filename part matters there on Simulator, so the remote end
@@ -53,13 +45,7 @@ default void pushFile(String remotePath, byte[] base64Data) {
     }
 
     /**
-     * Saves base64 encoded data as a media file on the remote mobile device.
-     * The server should have ifuse
-     * libraries installed and configured properly for this feature to work
-     * on real devices.
-     *
-     * @see <a href="https://github.com/libimobiledevice/ifuse">iFuse GitHub page</a>
-     * @see <a href="https://github.com/osxfuse/osxfuse/wiki/FAQ">osxFuse FAQ</a>
+     * Saves base64 encoded data as a media file on the remote system.
      *
      * @param remotePath See the documentation on {@link #pushFile(String, byte[])}
      * @param file Is an existing local file to be written to the remote device
@@ -68,7 +54,8 @@ default void pushFile(String remotePath, byte[] base64Data) {
     default void pushFile(String remotePath, File file) throws IOException {
         checkNotNull(file, "A reference to file should not be NULL");
         if (!file.exists()) {
-            throw new IOException(String.format("The given file %s doesn't exist", file.getAbsolutePath()));
+            throw new IOException(String.format("The given file %s doesn't exist",
+                    file.getAbsolutePath()));
         }
         pushFile(remotePath, Base64.encodeBase64(FileUtils.readFileToByteArray(file)));
     }

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

@@ -0,0 +1,59 @@
+/*
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * See the NOTICE file distributed with this work for additional
+ * information regarding copyright ownership.
+ * 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 io.appium.java_client;
+
+import static io.appium.java_client.MobileCommand.CLOSE_APP;
+import static io.appium.java_client.MobileCommand.LAUNCH_APP;
+import static io.appium.java_client.MobileCommand.RESET;
+
+@Deprecated
+public interface SupportsLegacyAppManagement extends ExecutesMethod {
+    /**
+     * Launches the app, which was provided in the capabilities at session creation,
+     * and (re)starts the session.
+     *
+     * @deprecated This method is deprecated and will be removed.
+     *     See https://github.com/appium/appium/issues/15807
+     */
+    @Deprecated
+    default void launchApp() {
+        execute(LAUNCH_APP);
+    }
+
+    /**
+     * Resets the currently running app together with the session.
+     *
+     * @deprecated This method is deprecated and will be removed.
+     *     See https://github.com/appium/appium/issues/15807
+     */
+    @Deprecated
+    default void resetApp() {
+        execute(RESET);
+    }
+
+    /**
+     * Close the app which was provided in the capabilities at session creation
+     * and quits the session.
+     *
+     * @deprecated This method is deprecated and will be removed.
+     *     See https://github.com/appium/appium/issues/15807
+     */
+    @Deprecated
+    default void closeApp() {
+        execute(CLOSE_APP);
+    }
+}

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

@@ -43,14 +43,14 @@
  * 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 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> {

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

@@ -31,9 +31,11 @@
 import io.appium.java_client.HasOnScreenKeyboard;
 import io.appium.java_client.HidesKeyboard;
 import io.appium.java_client.InteractsWithApps;
-import io.appium.java_client.InteractsWithFiles;
+import io.appium.java_client.PullsFiles;
 import io.appium.java_client.LocksDevice;
 import io.appium.java_client.PerformsTouchActions;
+import io.appium.java_client.PushesFiles;
+import io.appium.java_client.SupportsLegacyAppManagement;
 import io.appium.java_client.android.connection.HasNetworkConnection;
 import io.appium.java_client.android.geolocation.SupportsExtendedGeolocationCommands;
 import io.appium.java_client.android.nativekey.PressesKey;
@@ -66,8 +68,9 @@ public class AndroidDriver extends AppiumDriver implements
         PerformsTouchActions,
         HidesKeyboard,
         HasDeviceTime,
-        InteractsWithFiles,
+        PullsFiles,
         InteractsWithApps,
+        SupportsLegacyAppManagement,
         HasAppStrings,
         HasNetworkConnection,
         PushesFiles,