org.netbeans.html.geo.spi

Class GLProvider<Coords,Watch>

java.lang.Object

org.netbeans.html.geo.spi.GLProvider<Coords,Watch>

Type Parameters:

Watch - your chosen type to represent one query (one time) or watch (repeated) request - this type is used in start and stop methods.

Coords - your chosen type to represent geolocation coordinates - use in many methods in this class like GLProvider.latitude(java.lang.Object) and GLProvider.longitude(java.lang.Object).

public abstract class GLProvider<Coords,Watch>
extends Object

SPI for those who wish to provide their own way of obtaining geolocation. Subclass this class, implement its method and register it into the system. You can either use ServiceProvider to register globally, or one can register into BrwsrCtx (via context builder).

There is default system provider (used as a fallback) based on W3C's Geolocation specification - if you are running inside a browser that supports such standard and you are satisfied with its behavior, you don't have to register anything.

The provider serves two purposes:

1. It handles a geolocation request and creates a "watch" to represent it - to do so implement the start method and the stop method.
2. Once the location is found, the provider needs to call back with appropriate location information which can be extracted later via GLProvider.latitude(java.lang.Object) GLProvider.longitude(java.lang.Object), and other methods in this that also need to be implemented.

The provider is based on a singletonizer pattern (applied twice) and as such one is only required to subclass just the GLProvider and otherwise has freedom choosing what classes to use to represent coordinates and watches. For example if it is enough to use an array for coordinates and a long number for a watch, one can do:

 public final class MyGeoProvider extends GLProvider<Double[], Long> {
   // somehow implement the methods
 }
 

Since:

1.0

Author:

Jaroslav Tulach

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	GLProvider.Query Holds parameters describing the location query and is used by GLProvider to notify back results of its findings.

Constructor Summary

Constructors

Constructor and Description
GLProvider()

Method Summary

Modifier and Type	Method and Description
protected abstract double	accuracy(Coords coords) Extracts value for Position.Coordinates.getLatitude().
protected abstract Double	altitude(Coords coords) Extracts value for Position.Coordinates.getAltitude().
protected abstract Double	altitudeAccuracy(Coords coords) Extracts value for Position.Coordinates.getAltitudeAccuracy() - the altitude accuracy is specified in meters.
protected void	callback(GLProvider.Query c, long timestamp, Coords position, Exception ex) Invoke this method when your provider obtained requested location.
protected abstract Double	heading(Coords coords) Extracts value for Position.Coordinates.getHeading().
protected abstract double	latitude(Coords coords) Extracts value for Position.Coordinates.getLatitude().
protected abstract double	longitude(Coords coords) Extracts value for Position.Coordinates.getLatitude().
protected abstract Double	speed(Coords coords) Extracts value for Position.Coordinates.getSpeed().
protected abstract Watch	start(GLProvider.Query c) Start obtaining geolocation.
protected abstract void	stop(Watch watch) Called when a geolocation request should be stopped.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

GLProvider

public GLProvider()

Method Detail

start

protected abstract Watch start(GLProvider.Query c)

Start obtaining geolocation. When the client requests location (and your provider is found) this method should initialize the request or return null to give chance to another provider.

Parameters:

c - the query describing the request and to use when location is found - keep it, you'll need it later

Returns:

an object representing the request (so it can be stopped later) or null if this provider was unable to start the request

stop

protected abstract void stop(Watch watch)

Called when a geolocation request should be stopped.

Parameters:

watch - the watch returned when starting the request

callback

protected final void callback(GLProvider.Query c,
                              long timestamp,
                              Coords position,
                              Exception ex)

Invoke this method when your provider obtained requested location. This single method is used for notification of success (when ex argument is null and position is provided) or a failure (when ex argument is non-null). A successful requests leads in a call to Position.Handle.onLocation(net.java.html.geo.Position) while an error report leads to a call to Position.Handle.onError(java.lang.Exception). The actual call is sent to BrwsrCtx.execute(java.lang.Runnable) of context recorded when the GLProvider.Query was created to guarantee it happens on the right browser thread - however it may happen "later" when this method has already finished.

Parameters:

c - the query as provided when starting the request

timestamp - milliseconds since epoch when the location has been obtained

position - your own, internal, representation of geolocation coordinates - will be passed back to other methods of this class like GLProvider.latitude(java.lang.Object) and GLProvider.longitude(java.lang.Object). Can be null if ex is non-null

ex - an exception to signal an error - should be null when one notifies the successfully obtained position

latitude

protected abstract double latitude(Coords coords)

Extracts value for Position.Coordinates.getLatitude().

Parameters:

coords - your own internal representation of coordinates.

Returns:

geographic coordinate specified in decimal degrees.

longitude

protected abstract double longitude(Coords coords)

Extracts value for Position.Coordinates.getLatitude().

Parameters:

coords - your own internal representation of coordinates.

Returns:

geographic coordinate specified in decimal degrees.

accuracy

protected abstract double accuracy(Coords coords)

Extracts value for Position.Coordinates.getLatitude(). The accuracy attribute denotes the accuracy level of the latitude and longitude coordinates.

Parameters:

coords - your own internal representation of coordinates.

Returns:

accuracy in meters

altitude

protected abstract Double altitude(Coords coords)

Extracts value for Position.Coordinates.getAltitude(). Denotes the height of the position, specified in meters above the ellipsoid.

Parameters:

coords - your own internal representation of coordinates.

Returns:

value in meters, may return null, if the information is not available

altitudeAccuracy

protected abstract Double altitudeAccuracy(Coords coords)

Extracts value for Position.Coordinates.getAltitudeAccuracy() - the altitude accuracy is specified in meters.

Parameters:

coords - your own internal representation of coordinates.

Returns:

value in meters; may return null, if the information is not available

heading

protected abstract Double heading(Coords coords)

Extracts value for Position.Coordinates.getHeading(). Denotes the magnitude of the horizontal component of the device's current velocity and is specified in meters per second.

Parameters:

coords - your own internal representation of coordinates.

Returns:

may return null, if the information is not available

speed

protected abstract Double speed(Coords coords)

Extracts value for Position.Coordinates.getSpeed(). Denotes the magnitude of the horizontal component of the device's current velocity and is specified in meters per second.

Parameters:

coords - your own internal representation of coordinates.

Returns:

may return null, if the information is not available