Package com.vaadin.flow.component.geolocation

Class GeolocationWatcher

java.lang.Object
com.vaadin.flow.component.geolocation.GeolocationWatcher
All Implemented Interfaces:
Serializable
public class GeolocationWatcher extends Object implements Serializable
A handle to a geolocation watch session, returned by Geolocation.watchPosition(Component) and its overload.

Two ways to consume the stream of readings:

The underlying browser watch is cancelled automatically when the owning component detaches; call stop() to cancel sooner and resume() to restart on the same handle. Bindings and listeners survive stop/resume cycles.

The watch starts as soon as the owning component is attached to a UI: if the component is already attached when the watcher is created the watch starts immediately, otherwise it starts on first attach. Calling stop() before the first attach cancels the pending activation; the watcher can still be activated later by calling resume() on an attached owner.

See Also:

  • Method Details

    • positionSignal

      public Signal<GeolocationResult> positionSignal()
      Returns a read-only signal that holds the most recent reading.

      Starts as GeolocationPending until the browser reports its first value, then transitions to GeolocationPosition on every successful reading or GeolocationError on failure. After stop() the signal stops receiving updates but its last value stays readable; resume() resets the value to GeolocationPending and resumes updates. Subscribers stay attached across stop/resume cycles.

      Returns:
      a read-only signal reporting the latest reading

    • activeSignal

      public Signal<Boolean> activeSignal()
      Returns a read-only signal indicating whether the watcher is currently receiving updates. Flips to true on resume() and to false on stop() (or when the owner detaches). Useful for binding a "Stop tracking" toggle's state without tracking a separate flag.
      Returns:
      a read-only signal reporting whether the watch is active

    • addPositionListener

      public Registration addPositionListener(SerializableConsumer<GeolocationPosition> onPosition, SerializableConsumer<GeolocationError> onError)
      Subscribes to position and error pushes from the watch.

      onPosition fires for every GeolocationPosition the browser reports. onError fires for every GeolocationError the browser reports. Neither fires for the initial GeolocationPending state. Listeners stay attached across stop()/resume() cycles; remove them through the returned Registration.

      Both consumers are required and must be non-null. To opt out of either notification, pass pos -> {} or err -> {} explicitly.

      Parameters:
      onPosition - invoked on every successful reading, never null
      onError - invoked on every error reading, never null
      Returns:
      a registration that removes both listeners when removed
      Throws:
      NullPointerException - if either consumer is null

    • resume

      public void resume()
      Starts, or resumes, the underlying browser watch.

      Called automatically when the owner is attached to a UI: immediately if it is already attached when the watcher is created, otherwise on first attach. Call again after stop() to resume on the same handle — bindings and listeners stay attached and start receiving updates again. The signal resets to GeolocationPending on every resume. Calling resume() on an already-running watcher is a no-op.

      Throws:
      IllegalStateException - if the owner is not attached to a UI

    • stop

      public void stop()
      Cancels the underlying browser watch and tears down the server-side subscriptions.

      The browser stops reporting updates and positionSignal() stops changing. The last value remains readable. Detaching the owning component calls this automatically, so most applications never need to call it from a detach listener.

      Idempotent: calling it twice, or after the owner has already detached, does nothing extra. After stop() the watcher can be resumed with resume().