chore: Add non-W3C Location-management endpoints deprecated in Selenium client

Author: valfirst

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

@@ -73,6 +73,7 @@ public class AppiumDriver extends RemoteWebDriver implements
     // frequently used command parameters
     @Getter
     private final URL remoteAddress;
+    @Deprecated(forRemoval = true)
     protected final RemoteLocationContext locationContext;
     private final ExecuteMethod executeMethod;
     private final Set<String> absentExtensionNames = new HashSet<>();

src/main/java/io/appium/java_client/Location.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;
+
+/**
+ * Represents the physical location.
+ */
+public class Location extends org.openqa.selenium.html5.Location {
+    private final double latitude;
+    private final double longitude;
+    private final double altitude;
+
+    /**
+     * Create {@link Location} with latitude, longitude and altitude values.
+     *
+     * @param latitude latitude value.
+     * @param longitude longitude value.
+     * @param altitude altitude value.
+     */
+    public Location(double latitude, double longitude, double altitude) {
+        super(latitude, longitude, altitude);
+        this.latitude = latitude;
+        this.longitude = longitude;
+        this.altitude = altitude;
+    }
+
+    public double getLatitude() {
+        return latitude;
+    }
+
+    public double getLongitude() {
+        return longitude;
+    }
+
+    public double getAltitude() {
+        return altitude;
+    }
+
+    @Override
+    public String toString() {
+        return String.format("Latitude: %s, Longitude: %s, Altitude: %s", latitude, longitude, altitude);
+    }
+}

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

@@ -187,6 +187,9 @@ public class MobileCommand {
     public static final String GET_CURRENT_CONTEXT_HANDLE = "getCurrentContextHandle";
     public static final String SWITCH_TO_CONTEXT = "switchToContext";
 
+    public static final String GET_LOCATION = "getLocation";
+    public static final String SET_LOCATION = "setLocation";
+
     public static final Map<String, CommandInfo> commandRepository;
 
     static {
@@ -365,6 +368,9 @@ public class MobileCommand {
         commandRepository.put(GET_CONTEXT_HANDLES, getC("/session/:sessionId/contexts"));
         commandRepository.put(GET_CURRENT_CONTEXT_HANDLE, getC("/session/:sessionId/context"));
         commandRepository.put(SWITCH_TO_CONTEXT, postC("/session/:sessionId/context"));
+
+        commandRepository.put(GET_LOCATION, getC("/session/:sessionId/location"));
+        commandRepository.put(SET_LOCATION, postC("/session/:sessionId/location"));
     }
 
     /**

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

@@ -252,6 +252,7 @@ public AndroidBatteryInfo getBatteryInfo() {
     }
 
     @Override
+    @Deprecated(forRemoval = true)
     public RemoteLocationContext getLocationContext() {
         return locationContext;
     }

src/main/java/io/appium/java_client/android/geolocation/SupportsExtendedGeolocationCommands.java

@@ -18,7 +18,7 @@
 
 import io.appium.java_client.CommandExecutionHelper;
 import io.appium.java_client.ExecutesMethod;
-import org.openqa.selenium.remote.DriverCommand;
+import io.appium.java_client.MobileCommand;
 
 import java.util.Map;
 
@@ -31,7 +31,7 @@ public interface SupportsExtendedGeolocationCommands extends ExecutesMethod {
      * @param location The location object to set.
      */
     default void setLocation(AndroidGeoLocation location) {
-        CommandExecutionHelper.execute(this, Map.entry(DriverCommand.SET_LOCATION,
+        CommandExecutionHelper.execute(this, Map.entry(MobileCommand.SET_LOCATION,
                 Map.of("location", location.build())
         ));
     }

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

@@ -280,6 +280,7 @@ class IOSAlert implements Alert {
     }
 
     @Override
+    @Deprecated(forRemoval = true)
     public RemoteLocationContext getLocationContext() {
         return locationContext;
     }

src/main/java/io/appium/java_client/remote/SupportsLocation.java

@@ -16,19 +16,54 @@
 
 package io.appium.java_client.remote;
 
+import io.appium.java_client.CommandExecutionHelper;
+import io.appium.java_client.ExecutesMethod;
+import io.appium.java_client.Location;
+import io.appium.java_client.MobileCommand;
 import org.openqa.selenium.WebDriver;
-import org.openqa.selenium.html5.Location;
 import org.openqa.selenium.html5.LocationContext;
 import org.openqa.selenium.remote.html5.RemoteLocationContext;
 
-public interface SupportsLocation extends WebDriver, LocationContext {
-    public RemoteLocationContext getLocationContext();
+import java.util.Map;
 
+public interface SupportsLocation extends WebDriver, ExecutesMethod, LocationContext {
+
+    @Deprecated(forRemoval = true)
+    RemoteLocationContext getLocationContext();
+
+    /**
+     * Gets the physical location.
+     *
+     * @return A {@link Location} containing the location information. Returns null if the location is not available.
+     */
     default Location location() {
-        return getLocationContext().location();
+        Map<String, Number> result = CommandExecutionHelper.execute(this, MobileCommand.GET_LOCATION);
+        if (result == null) {
+            return null;
+        }
+        return new Location(
+                convertToDouble(result.get("latitude")),
+                convertToDouble(result.get("longitude")),
+                convertToDouble(result.get("altitude"))
+        );
+    }
+
+    private Double convertToDouble(Number number) {
+        if (number instanceof Double) {
+            return (Double) number;
+        } else if (number instanceof Long) {
+            return number.doubleValue();
+        } else {
+            throw new IllegalArgumentException("Can't convert to double: " + number);
+        }
     }
 
-    default void setLocation(Location location) {
-        getLocationContext().setLocation(location);
+    /**
+     * Sets the physical location.
+     *
+     * @param location A {@link Location} containing the new location information.
+     */
+    default void setLocation(org.openqa.selenium.html5.Location location) {
+        execute(MobileCommand.SET_LOCATION, Map.of("location", location));
     }
 }