Merge pull request #611 from mykola-mokhnach/duration_arg

Use java.time.Duration to represent time deltas instead of elementary types

Author: TikhomirovSergey

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

@@ -27,6 +27,7 @@
 
 import com.google.common.collect.ImmutableMap;
 
+import java.time.Duration;
 import java.util.AbstractMap;
 
 public interface InteractsWithApps extends ExecutesMethod {
@@ -68,11 +69,24 @@ default void resetApp() {
      * Runs the current app as a background app for the number of seconds
      * requested. This is a synchronous method, it returns after the back has
      * been returned to the foreground.
+     * This method is deprecated. Please use {@link #runAppInBackground(Duration)} instead.
      *
      * @param seconds Number of seconds to run App in background.
      */
+    @Deprecated
     default void runAppInBackground(int seconds) {
-        execute(RUN_APP_IN_BACKGROUND, ImmutableMap.of("seconds", seconds));
+        runAppInBackground(Duration.ofSeconds(seconds));
+    }
+
+    /**
+     * Runs the current app as a background app for the time
+     * requested. This is a synchronous method, it returns after the back has
+     * been returned to the foreground.
+     *
+     * @param duration The time to run App in background. Minimum time resolution is one second
+     */
+    default void runAppInBackground(Duration duration) {
+        execute(RUN_APP_IN_BACKGROUND, ImmutableMap.of("seconds", duration.getSeconds()));
     }
 
     /**

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

@@ -21,6 +21,7 @@
 import org.apache.commons.lang3.StringUtils;
 import org.openqa.selenium.remote.http.HttpMethod;
 
+import java.time.Duration;
 import java.util.AbstractMap;
 import java.util.HashMap;
 import java.util.Map;
@@ -330,13 +331,27 @@ public static ImmutableMap<String, Object> prepareArguments(String[] params,
     /**
      * This method forms a {@link java.util.Map} of parameters for the
      * device locking.
+     * The method is deprecated. Please use {@link #lockDeviceCommand(Duration)} instead.
      *
      * @param seconds seconds number of seconds to lock the screen for
      * @return  a key-value pair. The key is the command name. The value is a
      * {@link java.util.Map} command arguments.
      */
-    public static Map.Entry<String, Map<String, ?>>  lockDeviceCommand(int seconds) {
+    @Deprecated
+    public static Map.Entry<String, Map<String, ?>> lockDeviceCommand(int seconds) {
+        return lockDeviceCommand(Duration.ofSeconds(seconds));
+    }
+
+    /**
+     * This method forms a {@link java.util.Map} of parameters for the
+     * device locking.
+     *
+     * @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 java.util.Map} command arguments.
+     */
+    public static Map.Entry<String, Map<String, ?>> lockDeviceCommand(Duration duration) {
         return new AbstractMap.SimpleEntry<>(
-                LOCK, prepareArguments("seconds", seconds));
+                LOCK, prepareArguments("seconds", duration.getSeconds()));
     }
 }

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

@@ -191,6 +191,7 @@ static void checkXCoordinate(int x, Point location, Dimension size, int offSet)
 
     /**
      * Creates the swiping action. It is supposed to be performed inside the given element.
+     * The method is deprecated and has no effect.
      *
      * @param driver an instance that extends {@link AppiumDriver}
      * @param element the element that is going to be swiped
@@ -199,6 +200,7 @@ static void checkXCoordinate(int x, Point location, Dimension size, int offSet)
      * @param duration in milliseconds
      * @throws IllegalCoordinatesException when starting/ending coordinates are outside of the given element
      */
+    @Deprecated
     public void swipe(AppiumDriver<?> driver, MobileElement element, int offset1, int offset2,
         int duration) throws IllegalCoordinatesException {
         Point p = element.getCenter();

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

@@ -22,6 +22,8 @@
 import org.openqa.selenium.WebElement;
 import org.openqa.selenium.internal.HasIdentity;
 
+import java.time.Duration;
+
 /**
  * Used for Webdriver 3 touch actions
  * See the Webriver 3 spec
@@ -197,13 +199,25 @@ public TouchAction waitAction() {
 
     /**
      * Waits for specified amount of time to pass before continue to next touch action.
+     * The method is deprecated. Please use {@link #waitAction(Duration)} instead.
      *
      * @param ms time in milliseconds to wait.
      * @return this TouchAction, for chaining.
      */
+    @Deprecated
     public TouchAction waitAction(int ms) {
+        return waitAction(Duration.ofMillis(ms));
+    }
+
+    /**
+     * Waits for specified amount of time to pass before continue to next touch action.
+     *
+     * @param duration of the wait action. Minimum time reolution unit is one millisecond.
+     * @return this TouchAction, for chaining.
+     */
+    public TouchAction waitAction(Duration duration) {
         ActionParameter action = new ActionParameter("wait");
-        action.addParameter("ms", ms);
+        action.addParameter("ms", duration.toMillis());
         parameterBuilder.add(action);
         return this;
     }
@@ -222,14 +236,27 @@ public TouchAction longPress(WebElement el) {
 
     /**
      * Press and hold the at the center of an element until the contextmenu event has fired.
+     * This method is deprecated. Please use {@link #longPress(WebElement, Duration)} instead.
      *
      * @param el       element to long-press.
      * @param duration of the long-press, in milliseconds.
      * @return this TouchAction, for chaining.
      */
+    @Deprecated
     public TouchAction longPress(WebElement el, int duration) {
+        return longPress(el, Duration.ofMillis(duration));
+    }
+
+    /**
+     * Press and hold the at the center of an element until the contextmenu event has fired.
+     *
+     * @param el       element to long-press.
+     * @param duration of the long-press. Minimum time resolution unit is one millisecond.
+     * @return this TouchAction, for chaining.
+     */
+    public TouchAction longPress(WebElement el, Duration duration) {
         ActionParameter action = new ActionParameter("longPress", (HasIdentity) el);
-        action.addParameter("duration", duration);
+        action.addParameter("duration", duration.toMillis());
         parameterBuilder.add(action);
         return this;
     }
@@ -253,21 +280,37 @@ public TouchAction longPress(int x, int y) {
     /**
      * Press and hold the at an absolute position on the screen until the
      * contextmenu event has fired.
+     * The method is deprecated. Please use {@link #longPress(int, int, Duration)} instead.
      *
      * @param x        x coordinate.
      * @param y        y coordinate.
      * @param duration of the long-press, in milliseconds.
      * @return this TouchAction, for chaining.
      */
+    @Deprecated
     public TouchAction longPress(int x, int y, int duration) {
+        return longPress(x, y, Duration.ofMillis(duration));
+    }
+
+    /**
+     * Press and hold the at an absolute position on the screen until the
+     * contextmenu event has fired.
+     *
+     * @param x        x coordinate.
+     * @param y        y coordinate.
+     * @param duration of the long-press. Minimum time resolution unit is one millisecond.
+     * @return this TouchAction, for chaining.
+     */
+    public TouchAction longPress(int x, int y, Duration duration) {
         ActionParameter action = new ActionParameter("longPress");
         action.addParameter("x", x);
         action.addParameter("y", y);
-        action.addParameter("duration", duration);
+        action.addParameter("duration", duration.toMillis());
         parameterBuilder.add(action);
         return this;
     }
 
+
     /**
      * Press and hold the at an elements upper-left corner, offset by the given amount,
      * until the contextmenu event has fired.
@@ -288,18 +331,34 @@ public TouchAction longPress(WebElement el, int x, int y) {
     /**
      * Press and hold the at an elements upper-left corner, offset by the
      * given amount, until the contextmenu event has fired.
+     * The method is deprecated. Please use {@link #longPress(WebElement, int, int, Duration)} instead.
      *
      * @param el       element to long-press.
      * @param x        x offset.
      * @param y        y offset.
      * @param duration of the long-press, in milliseconds.
      * @return this TouchAction, for chaining.
      */
+    @Deprecated
     public TouchAction longPress(WebElement el, int x, int y, int duration) {
+        return longPress(el, x, y, Duration.ofMillis(duration));
+    }
+
+    /**
+     * Press and hold the at an elements upper-left corner, offset by the
+     * given amount, until the contextmenu event has fired.
+     *
+     * @param el       element to long-press.
+     * @param x        x offset.
+     * @param y        y offset.
+     * @param duration of the long-press. Minimum time resolution unit is one millisecond.
+     * @return this TouchAction, for chaining.
+     */
+    public TouchAction longPress(WebElement el, int x, int y, Duration duration) {
         ActionParameter action = new ActionParameter("longPress", (HasIdentity) el);
         action.addParameter("x", x);
         action.addParameter("y", y);
-        action.addParameter("duration", duration);
+        action.addParameter("duration", duration.toMillis());
         parameterBuilder.add(action);
         return this;
     }

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

@@ -26,6 +26,7 @@
 
 import org.openqa.selenium.remote.Response;
 
+import java.time.Duration;
 import java.util.Map;
 
 interface HasSettings extends ExecutesMethod {
@@ -53,7 +54,7 @@ default Map<String, Object> getSettings() {
         Map.Entry<String, Map<String, ?>> keyValuePair = getSettingsCommand();
         Response response = execute(keyValuePair.getKey(), keyValuePair.getValue());
 
-        return  ImmutableMap.<String, Object>builder()
+        return ImmutableMap.<String, Object>builder()
                 .putAll(Map.class.cast(response.getValue())).build();
     }
 
@@ -72,46 +73,106 @@ default void ignoreUnimportantViews(Boolean compress) {
 
     /**
      * invoke {@code setWaitForIdleTimeout} in {@code com.android.uiautomator.core.Configurator}
+     * This method is deprecated. Please use {@link #configuratorSetWaitForIdleTimeout(Duration)} instead.
      *
      * @param timeout in milliseconds. A negative value would reset to its default value
      */
+    @Deprecated
     default void configuratorSetWaitForIdleTimeout(int timeout) {
-        setSetting(Setting.WAIT_FOR_IDLE_TIMEOUT, timeout);
+        configuratorSetWaitForIdleTimeout(Duration.ofMillis(timeout));
+    }
+
+    /**
+     * invoke {@code setWaitForIdleTimeout} in {@code com.android.uiautomator.core.Configurator}
+     *
+     * @param timeout A negative value would reset to its default value. Minimum time unit
+     *                resolution is one millisecond
+     */
+    default void configuratorSetWaitForIdleTimeout(Duration timeout) {
+        setSetting(Setting.WAIT_FOR_IDLE_TIMEOUT, timeout.toMillis());
     }
 
     /**
      * invoke {@code setWaitForSelectorTimeout} in {@code com.android.uiautomator.core.Configurator}
+     * This method is deprecated. Please use {@link #configuratorSetWaitForSelectorTimeout(Duration)} instead.
      *
      * @param timeout in milliseconds. A negative value would reset to its default value
      */
+    @Deprecated
     default void configuratorSetWaitForSelectorTimeout(int timeout) {
-        setSetting(Setting.WAIT_FOR_SELECTOR_TIMEOUT, timeout);
+        configuratorSetWaitForSelectorTimeout(Duration.ofMillis(timeout));
+    }
+
+    /**
+     * invoke {@code setWaitForSelectorTimeout} in {@code com.android.uiautomator.core.Configurator}
+     *
+     * @param timeout A negative value would reset to its default value. Minimum time unit
+     *                resolution is one millisecond
+     */
+    default void configuratorSetWaitForSelectorTimeout(Duration timeout) {
+        setSetting(Setting.WAIT_FOR_SELECTOR_TIMEOUT, timeout.toMillis());
     }
 
     /**
      * invoke {@code setScrollAcknowledgmentTimeout} in {@code com.android.uiautomator.core.Configurator}
+     * This method is deprecated. Please use {@link #configuratorSetScrollAcknowledgmentTimeout(Duration)} instead.
      *
      * @param timeout in milliseconds. A negative value would reset to its default value
      */
+    @Deprecated
     default void configuratorSetScrollAcknowledgmentTimeout(int timeout) {
-        setSetting(Setting.WAIT_SCROLL_ACKNOWLEDGMENT_TIMEOUT, timeout);
+        configuratorSetScrollAcknowledgmentTimeout(Duration.ofMillis(timeout));
+    }
+
+    /**
+     * invoke {@code setScrollAcknowledgmentTimeout} in {@code com.android.uiautomator.core.Configurator}
+     *
+     * @param timeout A negative value would reset to its default value. Minimum time unit
+     *                resolution is one millisecond
+     */
+    default void configuratorSetScrollAcknowledgmentTimeout(Duration timeout) {
+        setSetting(Setting.WAIT_SCROLL_ACKNOWLEDGMENT_TIMEOUT, timeout.toMillis());
     }
 
     /**
      * invoke {@code configuratorSetKeyInjectionDelay} in {@code com.android.uiautomator.core.Configurator}
+     * This method is deprecated. Please use {@link #configuratorSetKeyInjectionDelay(Duration)} instead.
      *
      * @param delay in milliseconds. A negative value would reset to its default value
      */
+    @Deprecated
     default void configuratorSetKeyInjectionDelay(int delay) {
-        setSetting(Setting.KEY_INJECTION_DELAY, delay);
+        configuratorSetKeyInjectionDelay(Duration.ofMillis(delay));
+    }
+
+    /**
+     * invoke {@code configuratorSetKeyInjectionDelay} in {@code com.android.uiautomator.core.Configurator}
+     *
+     * @param delay A negative value would reset to its default value. Minimum time unit
+     *              resolution is one millisecond
+     */
+    default void configuratorSetKeyInjectionDelay(Duration delay) {
+        setSetting(Setting.KEY_INJECTION_DELAY, delay.toMillis());
     }
 
     /**
      * invoke {@code setActionAcknowledgmentTimeout} in {@code com.android.uiautomator.core.Configurator}
+     * This method is deprecated. Please use {@link #configuratorSetActionAcknowledgmentTimeout(Duration)} instead.
      *
      * @param timeout in milliseconds. A negative value would reset to its default value
      */
+    @Deprecated
     default void configuratorSetActionAcknowledgmentTimeout(int timeout) {
-        setSetting(Setting.WAIT_ACTION_ACKNOWLEDGMENT_TIMEOUT, timeout);
+        configuratorSetActionAcknowledgmentTimeout(Duration.ofMillis(timeout));
+    }
+
+    /**
+     * invoke {@code setActionAcknowledgmentTimeout} in {@code com.android.uiautomator.core.Configurator}
+     *
+     * @param timeout A negative value would reset to its default value. Minimum time unit
+     *                resolution is one millisecond
+     */
+    default void configuratorSetActionAcknowledgmentTimeout(Duration timeout) {
+        setSetting(Setting.WAIT_ACTION_ACKNOWLEDGMENT_TIMEOUT, timeout.toMillis());
     }
 }

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

@@ -21,14 +21,28 @@
 import io.appium.java_client.CommandExecutionHelper;
 import io.appium.java_client.ExecutesMethod;
 
+import java.time.Duration;
+
 public interface LocksIOSDevice extends ExecutesMethod {
     /**
      * Lock the device (bring it to the lock screen) for a given number of
      * seconds.
+     * Thsi method is deprecated. Please use {@link #lockDevice(Duration)} instead.
      *
      * @param seconds number of seconds to lock the screen for
      */
+    @Deprecated
     default void lockDevice(int seconds) {
-        CommandExecutionHelper.execute(this, lockDeviceCommand(seconds));
+        lockDevice(Duration.ofSeconds(seconds));
+    }
+
+    /**
+     * Lock the device (bring it to the lock screen) for a given number of
+     * seconds.
+     *
+     * @param duration for how long to lock the screen. Minimum time resolution is one second
+     */
+    default void lockDevice(Duration duration) {
+        CommandExecutionHelper.execute(this, lockDeviceCommand(duration));
     }
 }