Merge pull request #760 from TikhomirovSergey/mykola-mokhnach-actions_params

Mykola mokhnach's actions params:  The addition to the #756

Author: TikhomirovSergey

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

@@ -0,0 +1,29 @@
+/*
+ * 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.android;
+
+import io.appium.java_client.PerformsTouchActions;
+import io.appium.java_client.TouchAction;
+
+
+public class AndroidTouchAction extends TouchAction<AndroidTouchAction> {
+
+    public AndroidTouchAction(PerformsTouchActions performsTouchActions) {
+        super(performsTouchActions);
+    }
+
+}

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

@@ -1,12 +1,30 @@
+/*
+ * 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.ios;
 
+import static io.appium.java_client.touch.offset.ElementOption.element;
+
 import io.appium.java_client.PerformsTouchActions;
 import io.appium.java_client.TouchAction;
+import io.appium.java_client.touch.offset.ElementOption;
+import io.appium.java_client.touch.offset.PointOption;
 import org.openqa.selenium.WebElement;
-import org.openqa.selenium.internal.HasIdentity;
-
 
-public class IOSTouchAction extends TouchAction {
+public class IOSTouchAction extends TouchAction<IOSTouchAction> {
 
     public IOSTouchAction(PerformsTouchActions performsTouchActions) {
         super(performsTouchActions);
@@ -18,24 +36,35 @@ public IOSTouchAction(PerformsTouchActions performsTouchActions) {
      * @param el element to tap.
      * @param x  x offset.
      * @param y  y offset.
-     * @return this TouchAction, for chaining.
+     * @return this IOSTouchAction, for chaining.
+     * @deprecated use {@link #doubleTap(PointOption)} with count=2 instead.
      */
+    @Deprecated
     public IOSTouchAction doubleTap(WebElement el, int x, int y) {
-        ActionParameter action = new ActionParameter("doubleTap", (HasIdentity) el);
-        action.addParameter("x", x);
-        action.addParameter("y", y);
-        parameterBuilder.add(action);
-        return this;
+        return doubleTap(element(el, x, y));
     }
 
     /**
      * Double taps an element, offset from upper left corner.
      *
      * @param el element to tap.
-     * @return this TouchAction, for chaining.
+     * @return this IOSTouchAction, for chaining.
+     * @deprecated use {@link #doubleTap(PointOption)} with count=2 instead.
      */
+    @Deprecated
     public IOSTouchAction doubleTap(WebElement el) {
-        ActionParameter action = new ActionParameter("doubleTap", (HasIdentity) el);
+        return doubleTap(element(el));
+    }
+
+    /**
+     * Double taps using coordinates.
+     *
+     * @param doubleTapOption see {@link PointOption} and {@link ElementOption}..
+     * @return self-reference
+     */
+    public IOSTouchAction doubleTap(PointOption doubleTapOption) {
+        ActionParameter action = new ActionParameter("doubleTap",
+                doubleTapOption);
         parameterBuilder.add(action);
         return this;
     }

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

@@ -0,0 +1,40 @@
+/*
+ * 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.touch;
+
+import java.util.HashMap;
+import java.util.Map;
+
+public abstract class ActionOptions<T extends ActionOptions<T>> {
+    /**
+     * This method is automatically called before building
+     * options map to verify the consistency of the instance.
+     *
+     * @throws IllegalArgumentException if there are problems with this options map.
+     */
+    protected abstract void verify();
+
+    /**
+     * Creates a map based on the provided options.
+     *
+     * @return options mapping.
+     */
+    public Map<String, Object> build() {
+        verify();
+        return new HashMap<>();
+    }
+}

src/main/java/io/appium/java_client/touch/ActionOptions.java

@@ -0,0 +1,62 @@
+/*
+ * 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.touch;
+
+import static com.google.common.base.Preconditions.checkArgument;
+import static com.google.common.base.Preconditions.checkNotNull;
+import static java.util.Optional.ofNullable;
+
+import io.appium.java_client.touch.offset.AbstractOptionCombinedWithPosition;
+
+import java.time.Duration;
+import java.util.Map;
+
+public class LongPressOptions extends AbstractOptionCombinedWithPosition<LongPressOptions> {
+    protected Duration duration = null;
+
+    /**
+     * It creates an empty instance of {@link LongPressOptions}.
+     *
+     * @return an empty instance of {@link LongPressOptions}
+     */
+    public static LongPressOptions longPressOptions() {
+        return new LongPressOptions();
+    }
+
+    /**
+     * Set the long press duration.
+     *
+     * @param duration the value to set.
+     *                 Time resolution unit is 1 ms.
+     * @return this instance for chaining.
+     */
+    public LongPressOptions withDuration(Duration duration) {
+        checkNotNull(duration);
+        checkArgument(duration.toMillis() >= 0,
+                "Duration value should be greater or equal to zero");
+        this.duration = duration;
+        return this;
+    }
+
+    @Override
+    public Map<String, Object> build() {
+        final Map<String, Object> result = super.build();
+        ofNullable(duration).ifPresent(durationParam ->
+                result.put("duration", durationParam.toMillis()));
+        return result;
+    }
+}

src/main/java/io/appium/java_client/touch/LongPressOptions.java

@@ -0,0 +1,57 @@
+/*
+ * 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.touch;
+
+import static com.google.common.base.Preconditions.checkArgument;
+import static java.util.Optional.ofNullable;
+
+import io.appium.java_client.touch.offset.AbstractOptionCombinedWithPosition;
+
+import java.util.Map;
+
+public class TapOptions extends AbstractOptionCombinedWithPosition<TapOptions> {
+    private Integer tapsCount = null;
+
+    /**
+     * It creates an empty instance of {@link TapOptions}.
+     *
+     * @return the empty instance of {@link TapOptions}
+     */
+    public static TapOptions tapOptions() {
+        return new TapOptions();
+    }
+
+    /**
+     * Set the count of taps to perform.
+     *
+     * @param tapsCount the taps count to perform.
+     *                  The value should be greater than zero.
+     * @return this instance for chaining.
+     */
+    public TapOptions withTapsCount(int tapsCount) {
+        checkArgument(tapsCount > 0, "Taps count should be greater than zero");
+        this.tapsCount = tapsCount;
+        return this;
+    }
+
+    @Override
+    public Map<String, Object> build() {
+        final Map<String, Object> result = super.build();
+        ofNullable(tapsCount).ifPresent(integer -> result.put("count", integer));
+        return result;
+    }
+}

src/main/java/io/appium/java_client/touch/TapOptions.java

@@ -0,0 +1,65 @@
+/*
+ * 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.touch;
+
+import static com.google.common.base.Preconditions.checkArgument;
+import static com.google.common.base.Preconditions.checkNotNull;
+import static java.time.Duration.ofMillis;
+
+import java.time.Duration;
+import java.util.Map;
+
+public class WaitOptions extends ActionOptions<WaitOptions> {
+    protected Duration duration = ofMillis(0);
+
+    /**
+     * Creates and instance of {@link WaitOptions}.
+     *
+     * @param duration is the duration of the waiting.
+     * @return a built option.
+     */
+    public static WaitOptions waitOptions(Duration duration) {
+        return new WaitOptions().withDuration(duration);
+    }
+
+    /**
+     * Set the wait duration.
+     *
+     * @param duration the value to set.
+     *                 Time resolution unit is 1 ms.
+     * @return this instance for chaining.
+     */
+    public WaitOptions withDuration(Duration duration) {
+        checkNotNull(duration);
+        checkArgument(duration.toMillis() >= 0,
+                "Duration value should be greater or equal to zero");
+        this.duration = duration;
+        return this;
+    }
+
+    @Override
+    protected void verify() {
+        //there is nothing to check
+    }
+
+    @Override
+    public Map<String, Object> build() {
+        final Map<String, Object> result = super.build();
+        result.put("ms", duration.toMillis());
+        return result;
+    }
+}

src/main/java/io/appium/java_client/touch/WaitOptions.java

@@ -0,0 +1,50 @@
+package io.appium.java_client.touch.offset;
+
+import static java.util.Optional.ofNullable;
+
+import io.appium.java_client.touch.ActionOptions;
+
+import java.util.Map;
+
+public abstract class AbstractOptionCombinedWithPosition<T extends AbstractOptionCombinedWithPosition<T>>
+        extends ActionOptions<AbstractOptionCombinedWithPosition<T>> {
+    private ActionOptions<?> positionOption;
+
+    /**
+     * Some actions may require coordinates. Invocation of this method
+     * replaces the result of previous {@link #withElement(ElementOption)} invocation.
+     *
+     * @param positionOption required coordinates.     *
+     * @return self-reference
+     */
+    public T withPosition(PointOption positionOption) {
+        this.positionOption = positionOption;
+        return (T) this;
+    }
+
+    /**
+     * Most of touch action may use position which is relative to some element. In order to unify
+     * this behaviour this method was added. Invocation of this method
+     * replaces the result of previous {@link #withPosition(PointOption)} invocation.
+     *
+     * @param element required position which is relative to some element
+     * @return self-reference
+     */
+    public T withElement(ElementOption element) {
+        positionOption = element;
+        return (T) this;
+    }
+
+    protected void verify() {
+        ofNullable(positionOption).orElseThrow(() ->
+                new IllegalArgumentException("Some coordinates or an offset from an element should "
+                        + "be defined. Use withPosition or withElement methods"));
+    }
+
+    @Override
+    public Map<String, Object> build() {
+        final Map<String, Object> result = super.build();
+        result.putAll(positionOption.build());
+        return result;
+    }
+}