Repeatable annotations & HasSessionDetails API

docs/Page-objects.md

@@ -80,7 +80,10 @@ List<RemoteWebElement> someElements;
 
 # Also it is possible to define chained or any possible locators.
 
-- Chained
+## - Chained
+
+### If you use build versions < 5.x.x
+
 ```java
 import org.openqa.selenium.remote.RemoteWebElement;
 import io.appium.java_client.pagefactory.*;
@@ -98,7 +101,52 @@ RemoteWebElement someElement;
 List<RemoteWebElement> someElements;
 ```
 
-- Any possible
+### If you use build versions >= 5.x.x 
+
+```java
+import org.openqa.selenium.remote.RemoteWebElement;
+import io.appium.java_client.pagefactory.*;
+import org.openqa.selenium.support.FindBys;
+import org.openqa.selenium.support.FindBy;
+
+@FindBys({@FindBy(someStrategy1), @FindBy(someStrategy2)}) 
+@AndroidFindBy(someStrategy1) @AndroidFindBy(someStrategy2)
+@iOSFindBy(someStrategy1) @iOSFindBy(someStrategy2) 
+RemoteWebElement someElement;
+
+@FindBys({@FindBy(someStrategy1), @FindBy(someStrategy2)}) 
+@AndroidFindBy(someStrategy1) @AndroidFindBy(someStrategy2)
+@iOSFindBy(someStrategy1) @iOSFindBy(someStrategy2)
+List<RemoteWebElement> someElements;
+```
+
+or 
+
+```java
+import org.openqa.selenium.remote.RemoteWebElement;
+import io.appium.java_client.pagefactory.*;
+import org.openqa.selenium.support.FindBys;
+import org.openqa.selenium.support.FindBy;
+
+import static io.appium.java_client.pagefactory.LocatorGroupStrategy.CHAIN;
+
+@HowToUseLocators(androidAutomation = CHAIN, iOSAutomation = CHAIN)
+@FindBys({@FindBy(someStrategy1), @FindBy(someStrategy2)}) 
+@AndroidFindBy(someStrategy1) @AndroidFindBy(someStrategy2)
+@iOSFindBy(someStrategy1) @iOSFindBy(someStrategy2) 
+RemoteWebElement someElement;
+
+@HowToUseLocators(androidAutomation = CHAIN, iOSAutomation = CHAIN)
+@FindBys({@FindBy(someStrategy1), @FindBy(someStrategy2)}) 
+@AndroidFindBy(someStrategy1) @AndroidFindBy(someStrategy2)
+@iOSFindBy(someStrategy1) @iOSFindBy(someStrategy2)
+List<RemoteWebElement> someElements;
+```
+
+## - Any possible
+
+### If you use build versions < 5.x.x
+
 ```java
 import org.openqa.selenium.remote.RemoteWebElement;
 import io.appium.java_client.pagefactory.*;
@@ -116,6 +164,29 @@ RemoteWebElement someElement;
 List<RemoteWebElement> someElements;
 ```
 
+### If you use build versions >= 5.x.x
+
+```java
+import org.openqa.selenium.remote.RemoteWebElement;
+import io.appium.java_client.pagefactory.*;
+import org.openqa.selenium.support.FindBy;
+import org.openqa.selenium.support.FindByAll;
+
+import static io.appium.java_client.pagefactory.LocatorGroupStrategy.ALL_POSSIBLE;
+
+@HowToUseLocators(androidAutomation = ALL_POSSIBLE, iOSAutomation = ALL_POSSIBLE)
+@FindAll{@FindBy(someStrategy1), @FindBy(someStrategy2)}) 
+@AndroidFindBy(someStrategy1) @AndroidFindBy(someStrategy2) 
+@iOSFindBy(someStrategy1) @iOSFindBy(someStrategy2) 
+RemoteWebElement someElement;
+
+@HowToUseLocators(androidAutomation = ALL_POSSIBLE, iOSAutomation = ALL_POSSIBLE)
+@FindAll({@FindBy(someStrategy1), @FindBy(someStrategy2)}) 
+@AndroidFindBy(someStrategy1) @AndroidFindBy(someStrategy2)
+@iOSFindBy(someStrategy1) @iOSFindBy(someStrategy2)
+List<RemoteWebElement> someElements;
+```
+
 # Appium Java client is integrated with Selenium PageFactory by AppiumFieldDecorator. 
 
 Object fields are populated as below: 

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

@@ -14,13 +14,10 @@
  * limitations under the License.
  */
 
-
 package io.appium.java_client;
 
 import static com.google.common.base.Preconditions.checkNotNull;
 
-import static io.appium.java_client.MobileCommand.GET_SESSION;
-
 import com.google.common.collect.ImmutableMap;
 
 import io.appium.java_client.remote.AppiumCommandExecutor;
@@ -54,7 +51,6 @@
 import java.net.URL;
 import java.util.LinkedHashSet;
 import java.util.List;
-import java.util.Map;
 import java.util.Set;
 
 /**
@@ -447,13 +443,4 @@ private TouchAction createTap(int x, int y, int duration) {
     public URL getRemoteAddress() {
         return remoteAddress;
     }
-
-    /**
-     * @return a map with values that hold session details.
-     *
-     */
-    public Map<String, Object> getSessionDetails() {
-        Response response = execute(GET_SESSION);
-        return (Map<String, Object>) response.getValue();
-    }
 }

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

@@ -0,0 +1,38 @@
+/*
+ * 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.GET_SESSION;
+
+import org.openqa.selenium.remote.Response;
+
+import java.util.Map;
+
+public interface HasSessionDetails extends ExecutesMethod {
+    /**
+     * @return a map with values that hold session details.
+     *
+     */
+    default Map<String, Object> getSessionDetails() {
+        Response response = execute(GET_SESSION);
+        return (Map<String, Object>) response.getValue();
+    }
+
+    default Object getSessionDetail(String detail) {
+        return getSessionDetails().get(detail);
+    }
+}

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

@@ -37,7 +37,8 @@
 public interface MobileDriver<T extends WebElement> extends WebDriver, PerformsTouchActions, ContextAware, Rotatable,
     FindsByAccessibilityId<T>, LocationContext, DeviceActionShortcuts, TouchShortcuts,
     InteractsWithFiles, InteractsWithApps, HasAppStrings, FindsByClassName, FindsByCssSelector, FindsById,
-        FindsByLinkText, FindsByName, FindsByTagName, FindsByXPath, FindsByFluentSelector<T>, ExecutesMethod {
+        FindsByLinkText, FindsByName, FindsByTagName, FindsByXPath, FindsByFluentSelector<T>, ExecutesMethod,
+        HasSessionDetails {
 
     List<T> findElements(By by);
 

src/main/java/io/appium/java_client/pagefactory/AndroidFindAll.java

@@ -26,7 +26,12 @@
  * series of {@link io.appium.java_client.pagefactory.AndroidFindBy} tags
  * It will then search for all elements that match any criteria. Note that elements
  * are not guaranteed to be in document order.
+ * It is deprecated. Set of {@link io.appium.java_client.pagefactory.AndroidFindBy}
+ * can be defined without this annotation. To define the correct way how to use
+ * the defined set please take a look at {@link HowToUseLocators}. The article.
+ * https://docs.oracle.com/javase/tutorial/java/annotations/repeating.html.
  */
+@Deprecated
 @Retention(RetentionPolicy.RUNTIME) @Target({ElementType.FIELD, ElementType.TYPE})
 public @interface AndroidFindAll {
     /**

src/main/java/io/appium/java_client/pagefactory/AndroidFindBy.java

@@ -17,6 +17,7 @@
 package io.appium.java_client.pagefactory;
 
 import java.lang.annotation.ElementType;
+import java.lang.annotation.Repeatable;
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
@@ -30,6 +31,7 @@
  * using Android UI selectors, accessibility, id, name, class name, tag and xpath
  */
 @Retention(RetentionPolicy.RUNTIME) @Target({ElementType.FIELD, ElementType.TYPE})
+@Repeatable(AndroidFindBySet.class)
 public @interface AndroidFindBy {
     /**
      * It is an is Android UIAutomator string.

src/main/java/io/appium/java_client/pagefactory/AndroidFindBySet.java

@@ -0,0 +1,36 @@
+/*
+ * 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.pagefactory;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Defines set of chained/possible locators. Each one locator
+ * should be defined with {@link io.appium.java_client.pagefactory.AndroidFindBy}
+ */
+@Target(value = {ElementType.TYPE, ElementType.FIELD})
+@Retention(value = RetentionPolicy.RUNTIME)
+public @interface AndroidFindBySet {
+    /**
+     * @return an array of {@link io.appium.java_client.pagefactory.AndroidFindBy} which builds a sequence of
+     * the chained searching for elements or a set of possible locators
+     */
+    AndroidFindBy[] value();
+}

src/main/java/io/appium/java_client/pagefactory/AndroidFindBys.java

@@ -24,7 +24,12 @@
 /**
  * Used to mark a field on a Page Object to indicate that lookup should use
  * a series of {@link io.appium.java_client.pagefactory.AndroidFindBy} tags.
+ * It is deprecated. Set of {@link io.appium.java_client.pagefactory.AndroidFindBy}
+ * can be defined without this annotation. To define the correct way how to use
+ * the defined set please take a look at {@link HowToUseLocators}. The article.
+ * https://docs.oracle.com/javase/tutorial/java/annotations/repeating.html.
  */
+@Deprecated
 @Retention(RetentionPolicy.RUNTIME) @Target({ElementType.FIELD, ElementType.TYPE})
 public @interface AndroidFindBys {
     /**

src/main/java/io/appium/java_client/pagefactory/AppiumFieldDecorator.java

@@ -17,11 +17,10 @@
 package io.appium.java_client.pagefactory;
 
 import static io.appium.java_client.pagefactory.utils.ProxyFactory.getEnhancedProxy;
-import static io.appium.java_client.pagefactory.utils.WebDriverUnpackUtility.getAutomation;
-import static io.appium.java_client.pagefactory.utils.WebDriverUnpackUtility.getPlatform;
 import static io.appium.java_client.pagefactory.utils.WebDriverUnpackUtility
     .unpackWebDriverFromSearchContext;
 
+import io.appium.java_client.HasSessionDetails;
 import io.appium.java_client.MobileElement;
 import io.appium.java_client.TouchableElement;
 import io.appium.java_client.android.AndroidDriver;
@@ -94,6 +93,24 @@ public class AppiumFieldDecorator implements FieldDecorator {
     private final String automation;
     private final TimeOutDuration timeOutDuration;
 
+    private static String extractSessionData(WebDriver driver, String parameter) {
+        if (driver == null) {
+            return null;
+        }
+
+        if (!(driver instanceof HasSessionDetails)) {
+            return null;
+        }
+
+        Object parameterValue = HasSessionDetails.class.cast(driver).getSessionDetail(parameter);
+
+        if (parameterValue == null) {
+            return null;
+        }
+
+        return String.valueOf(parameterValue);
+    }
+
     public AppiumFieldDecorator(SearchContext context, long implicitlyWaitTimeOut,
         TimeUnit timeUnit) {
         this(context, new TimeOutDuration(implicitlyWaitTimeOut, timeUnit));
@@ -109,8 +126,8 @@ public AppiumFieldDecorator(SearchContext context, long implicitlyWaitTimeOut,
      */
     public AppiumFieldDecorator(SearchContext context, TimeOutDuration timeOutDuration) {
         this.originalDriver = unpackWebDriverFromSearchContext(context);
-        platform = getPlatform(originalDriver);
-        automation = getAutomation(originalDriver);
+        platform = extractSessionData(originalDriver, "platformName");
+        automation = extractSessionData(originalDriver, "automationName");
         this.timeOutDuration = timeOutDuration;
 
         defaultElementFieldDecoracor = new DefaultFieldDecorator(