Package com.vaadin.flow.component.geolocation

Interface GeolocationClient

All Superinterfaces:

Serializable

@NullMarked
public interface GeolocationClient
extends Serializable

Port between the Geolocation facade and whatever delivers actual position data — the browser in production, an in-memory test driver in unit tests.

Framework internal. Application code does not implement this interface directly. Replacement clients are installed at facade construction time by registering a GeolocationClientFactory through Vaadin's Lookup; Geolocation then hands the resulting client every get(com.vaadin.flow.component.geolocation.GeolocationOptions), startWatch(com.vaadin.flow.component.Component, com.vaadin.flow.component.geolocation.GeolocationOptions, com.vaadin.flow.function.SerializableConsumer<com.vaadin.flow.component.geolocation.GeolocationResult>) and subscribeAvailability(com.vaadin.flow.function.SerializableConsumer<com.vaadin.flow.component.geolocation.GeolocationAvailability>) call. When no factory is registered, Geolocation uses the built-in browser-backed client.

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 tracker 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<GeolocationOutcome>	get(@Nullable GeolocationOptions options)	Issues a one-shot position request.
GeolocationClient.WatchHandle	startWatch(Component owner, @Nullable 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<GeolocationOutcome> get(@Nullable 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, or null for browser defaults

Returns:

a future that completes with the outcome on the UI thread

startWatch

GeolocationClient.WatchHandle startWatch(Component owner,
 @Nullable 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, or null for 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 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 the facade must not call them.