feat(geolocation): add addPositionListener to GeolocationTracker (#24268)

Artur- · web-flow · commit 96d88028ce24 · 2026-05-06T06:48:07.000Z
Lets callers subscribe to tracking updates with plain callbacks instead
of subscribing to valueSignal(), mirroring the W3C
watchPosition(success, error) pair. Listeners persist across
stop()/resume() cycles and never see the GeolocationPending state.
diff --git a/flow-server/src/main/java/com/vaadin/flow/component/geolocation/GeolocationTracker.java b/flow-server/src/main/java/com/vaadin/flow/component/geolocation/GeolocationTracker.java
@@ -16,10 +16,14 @@
 package com.vaadin.flow.component.geolocation;
 
 import java.io.Serializable;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Objects;
 
 import org.jspecify.annotations.Nullable;
 
 import com.vaadin.flow.component.Component;
+import com.vaadin.flow.function.SerializableConsumer;
 import com.vaadin.flow.shared.Registration;
 import com.vaadin.flow.signals.Signal;
 import com.vaadin.flow.signals.local.ValueSignal;
@@ -54,6 +58,9 @@ public class GeolocationTracker implements Serializable {
     private final Signal<Boolean> activeSignalReadOnly = activeSignal
             .asReadonly();
 
+    private final List<SerializableConsumer<GeolocationPosition>> positionListeners = new ArrayList<>();
+    private final List<SerializableConsumer<GeolocationError>> errorListeners = new ArrayList<>();
+
     private final Component owner;
     private final @Nullable GeolocationOptions options;
     private final GeolocationClient client;
@@ -111,6 +118,43 @@ public Signal<Boolean> activeSignal() {
         return activeSignalReadOnly;
     }
 
+    /**
+     * Adds a listener pair that is notified on every reading the browser
+     * reports. The listener-based equivalent of subscribing to
+     * {@link #valueSignal()} for callers that prefer plain callbacks over
+     * signals.
+     * <p>
+     * On every successful reading {@code onSuccess} is invoked with the
+     * {@link GeolocationPosition}. If the browser reports an error instead
+     * {@code onError} is invoked with the {@link GeolocationError}. The initial
+     * {@link GeolocationPending} state is never delivered to listeners — they
+     * only see real outcomes, mirroring the W3C
+     * {@code watchPosition(success, error)} pair.
+     * <p>
+     * Listeners survive {@link #stop()} / {@link #resume()} cycles; remove them
+     * via {@link Registration#remove()} on the returned registration. Both
+     * callbacks are invoked on the UI thread.
+     *
+     * @param onSuccess
+     *            invoked with each successful position reading; not
+     *            {@code null}
+     * @param onError
+     *            invoked when the browser reports an error; not {@code null}
+     * @return a registration that removes both listeners when called
+     */
+    public Registration addPositionListener(
+            SerializableConsumer<GeolocationPosition> onSuccess,
+            SerializableConsumer<GeolocationError> onError) {
+        Objects.requireNonNull(onSuccess, "onSuccess listener cannot be null");
+        Objects.requireNonNull(onError, "onError listener cannot be null");
+        positionListeners.add(onSuccess);
+        errorListeners.add(onError);
+        return () -> {
+            positionListeners.remove(onSuccess);
+            errorListeners.remove(onError);
+        };
+    }
+
     /**
      * Starts, or resumes, the underlying browser watch.
      * <p>
@@ -129,10 +173,33 @@ public void resume() {
         activeSignal.set(Boolean.TRUE);
         valueSignal.set(new GeolocationPending());
 
-        handle = client.startWatch(owner, options, valueSignal::set);
+        handle = client.startWatch(owner, options, this::handleResult);
         detachRegistration = owner.addDetachListener(e -> stop());
     }
 
+    private void handleResult(GeolocationResult result) {
+        valueSignal.set(result);
+        switch (result) {
+        case GeolocationPosition position -> {
+            for (SerializableConsumer<GeolocationPosition> listener : new ArrayList<>(
+                    positionListeners)) {
+                listener.accept(position);
+            }
+        }
+        case GeolocationError error -> {
+            for (SerializableConsumer<GeolocationError> listener : new ArrayList<>(
+                    errorListeners)) {
+                listener.accept(error);
+            }
+        }
+        case GeolocationPending pending -> {
+            // Intentionally not dispatched to listeners — Pending is the
+            // initial state set by resume(), not an outcome the W3C
+            // watchPosition(success, error) pair would fire.
+        }
+        }
+    }
+
     /**
      * Cancels the underlying browser watch and tears down the server-side
      * listeners.
diff --git a/flow-server/src/test/java/com/vaadin/flow/component/geolocation/GeolocationTest.java b/flow-server/src/test/java/com/vaadin/flow/component/geolocation/GeolocationTest.java
@@ -32,6 +32,7 @@
 import com.vaadin.flow.dom.Element;
 import com.vaadin.flow.internal.JacksonUtils;
 import com.vaadin.flow.internal.nodefeature.ElementListenerMap;
+import com.vaadin.flow.shared.Registration;
 import com.vaadin.tests.util.MockUI;
 
 import static org.junit.jupiter.api.Assertions.assertDoesNotThrow;
@@ -497,6 +498,120 @@ void active_signalReflectsResumeAndStop() {
         assertTrue(tracker.activeSignal().peek());
     }
 
+    // --- addPositionListener() tests ---
+
+    @Test
+    void addPositionListener_dispatchesPositionAndError() {
+        TestComponent component = new TestComponent();
+        ui.add(component);
+
+        GeolocationTracker tracker = ui.getGeolocation().track(component);
+        List<GeolocationPosition> positions = new ArrayList<>();
+        List<GeolocationError> errors = new ArrayList<>();
+        tracker.addPositionListener(positions::add, errors::add);
+
+        ObjectNode posData = JacksonUtils.createObjectNode();
+        ObjectNode posDetail = JacksonUtils.createObjectNode();
+        ObjectNode coords = JacksonUtils.createObjectNode();
+        coords.put("latitude", 60.1699);
+        coords.put("longitude", 24.9384);
+        coords.put("accuracy", 10.0);
+        posDetail.set("coords", coords);
+        posDetail.put("timestamp", 1700000000000L);
+        posData.set("event.detail", posDetail);
+        fireEvent(component.getElement(), "vaadin-geolocation-position",
+                posData);
+
+        ObjectNode errData = JacksonUtils.createObjectNode();
+        ObjectNode errDetail = JacksonUtils.createObjectNode();
+        errDetail.put("code", GeolocationErrorCode.TIMEOUT.code());
+        errDetail.put("message", "Timeout");
+        errData.set("event.detail", errDetail);
+        fireEvent(component.getElement(), "vaadin-geolocation-error", errData);
+
+        assertEquals(1, positions.size());
+        assertEquals(60.1699, positions.get(0).coords().latitude());
+        assertEquals(1, errors.size());
+        assertEquals(GeolocationErrorCode.TIMEOUT, errors.get(0).errorCode());
+    }
+
+    @Test
+    void addPositionListener_registrationStopsDelivery() {
+        TestComponent component = new TestComponent();
+        ui.add(component);
+
+        GeolocationTracker tracker = ui.getGeolocation().track(component);
+        List<GeolocationPosition> positions = new ArrayList<>();
+        Registration registration = tracker.addPositionListener(positions::add,
+                err -> {
+                });
+
+        registration.remove();
+
+        ObjectNode posData = JacksonUtils.createObjectNode();
+        ObjectNode posDetail = JacksonUtils.createObjectNode();
+        ObjectNode coords = JacksonUtils.createObjectNode();
+        coords.put("latitude", 60.0);
+        coords.put("longitude", 25.0);
+        coords.put("accuracy", 10.0);
+        posDetail.set("coords", coords);
+        posDetail.put("timestamp", 1700000000000L);
+        posData.set("event.detail", posDetail);
+        fireEvent(component.getElement(), "vaadin-geolocation-position",
+                posData);
+
+        assertTrue(positions.isEmpty(),
+                "removed listener must not receive subsequent updates");
+    }
+
+    @Test
+    void addPositionListener_survivesStopResume() {
+        TestComponent component = new TestComponent();
+        ui.add(component);
+
+        GeolocationTracker tracker = ui.getGeolocation().track(component);
+        List<GeolocationPosition> positions = new ArrayList<>();
+        tracker.addPositionListener(positions::add, err -> {
+        });
+
+        tracker.stop();
+        tracker.resume();
+
+        ObjectNode posData = JacksonUtils.createObjectNode();
+        ObjectNode posDetail = JacksonUtils.createObjectNode();
+        ObjectNode coords = JacksonUtils.createObjectNode();
+        coords.put("latitude", 60.0);
+        coords.put("longitude", 25.0);
+        coords.put("accuracy", 10.0);
+        posDetail.set("coords", coords);
+        posDetail.put("timestamp", 1700000000000L);
+        posData.set("event.detail", posDetail);
+        fireEvent(component.getElement(), "vaadin-geolocation-position",
+                posData);
+
+        assertEquals(1, positions.size());
+        assertEquals(60.0, positions.get(0).coords().latitude());
+    }
+
+    @Test
+    void addPositionListener_pendingIsSilent() {
+        TestComponent component = new TestComponent();
+        ui.add(component);
+
+        GeolocationTracker tracker = ui.getGeolocation().track(component);
+        List<GeolocationPosition> positions = new ArrayList<>();
+        List<GeolocationError> errors = new ArrayList<>();
+        tracker.addPositionListener(positions::add, errors::add);
+
+        // resume() resets the signal to Pending — listeners must stay silent
+        // since they only see real outcomes.
+        tracker.stop();
+        tracker.resume();
+
+        assertTrue(positions.isEmpty());
+        assertTrue(errors.isEmpty());
+    }
+
     // --- availability() / availability-change listener tests ---
 
     @Test
