Package com.vaadin.flow.component.geolocation

Interface GeolocationClient

All Superinterfaces:

Serializable

@NullMarked
public interface GeolocationClient
extends Serializable

Framework-internal port between the Geolocation static API and whatever delivers actual position data — the browser in production, an in-memory driver in browserless tests. Application code does not interact with this interface; it is exposed so external test drivers can replace the production client via UIInternals.setGeolocationClient(GeolocationClient).

Threading: all callbacks on this interface (the future returned by get(com.vaadin.flow.component.geolocation.GeolocationOptions), the onUpdate consumer passed to startWatch(com.vaadin.flow.component.Component, com.vaadin.flow.component.geolocation.GeolocationOptions, com.vaadin.flow.function.SerializableConsumer<com.vaadin.flow.component.geolocation.GeolocationResult>), and the onChange consumer passed to subscribeAvailability(com.vaadin.flow.function.SerializableConsumer<com.vaadin.flow.component.geolocation.GeolocationAvailability>)) must be invoked on the UI thread.

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static interface	GeolocationClient.WatchHandle	Handle to a watch session.

Method Summary

Modifier and Type	Method	Description
void	close()	Releases any resources held by this client.
GeolocationAvailability	currentAvailability()	Returns the most recently observed availability.
CompletableFuture<com.vaadin.flow.component.geolocation.GeolocationOutcome>	get(GeolocationOptions options)	Issues a one-shot position request.
GeolocationClient.WatchHandle	startWatch(Component owner, GeolocationOptions options, SerializableConsumer<GeolocationResult> onUpdate)	Starts a watch session bound to owner.
Registration	subscribeAvailability(SerializableConsumer<GeolocationAvailability> onChange)	Subscribes to availability changes.

Method Details

get

CompletableFuture<com.vaadin.flow.component.geolocation.GeolocationOutcome> get(GeolocationOptions options)

Issues a one-shot position request. The future completes once the client has an answer (a position or an error).

Parameters:

options - tuning options, never null; pass an empty GeolocationOptions to use browser defaults

Returns:

a future that completes with the outcome on the UI thread

startWatch

GeolocationClient.WatchHandle startWatch(Component owner,
 GeolocationOptions options,
 SerializableConsumer<GeolocationResult> onUpdate)

Starts a watch session bound to owner. Position and error pushes are delivered via onUpdate. The returned handle is used to stop the watch and to query whether it is still active.

Parameters:

owner - the component that owns this watch; detaching the component does not auto-stop the watch — the caller is responsible

options - tuning options, never null; pass an empty GeolocationOptions to use browser defaults

onUpdate - consumer invoked on the UI thread for every push

Returns:

a handle for stopping the watch

subscribeAvailability

Registration subscribeAvailability(SerializableConsumer<GeolocationAvailability> onChange)

Subscribes to availability changes. The returned registration removes the subscription.

Parameters:

onChange - consumer invoked on the UI thread for every availability change

Returns:

a registration that removes the subscription when called

currentAvailability

GeolocationAvailability currentAvailability()

Returns the most recently observed availability. Implementations must seed an initial value at construction; the result is never null.

Returns:

the current availability

close

void close()

Releases any resources held by this client. Called when one client is being replaced by another (e.g. when a test driver is installed) and on UI detach. Idempotent: calling more than once is a no-op. After close(), the behavior of get(com.vaadin.flow.component.geolocation.GeolocationOptions) and startWatch(com.vaadin.flow.component.Component, com.vaadin.flow.component.geolocation.GeolocationOptions, com.vaadin.flow.function.SerializableConsumer<com.vaadin.flow.component.geolocation.GeolocationResult>) is undefined and callers must not invoke them.