703 Position Specification

703.1 Introduction

The Position class is a utility providing bundle developers with a consistent way of handling geographic positions in OSGi applications. The Position class is intended to be used with the Wire Admin service but has wider applicability.

The Position class is designed to be compatible with the Global Positioning System (GPS). This specification will not define or explain the complexities of positioning information. It is assumed that the reader has the appropriate background to understand this information.

703.1.1 Essentials

  • Position - Provide an information object that has well defined semantics for a position.

  • WGS-84 - Use the World Geodetic System 84 as the datum.

  • Speed - Provide speed and track information.

  • Errors - Position information always has certain errors or cannot be measured at all. This information must be available to the users of the information.

  • Units - Use SI units for all measurements.

  • Wire Admin - This specification must work within the Wire Admin service.

703.1.2 Entities

  • Position - An object containing the different aspects of a position.

  • Measurement - Contains a typed measurement made at a certain time and with a specified error.

Figure 703.1 Class Diagram, org.osgi.util.position

Class Diagram, org.osgi.util.position

703.2 Positioning

The Position class is used to give information about the position and movement of a vehicle with a specified amount of uncertainty. The position is based on WGS-84.

The Position class offers the following information:

  • getLatitude() - The WGS-84 latitude of the current position. The unit of a latitude must be rad (radians).

  • getLongitude() - The WGS-84 longitude of the current position. The unit of a longitude must be rad (radians).

  • getAltitude() - Altitude is expressed as height in meters above the WGS-84 ellipsoid. This value can differ from the actual height above mean sea level depending on the place on earth where the measurement is taken place. This value is not corrected for the geoid.

  • getTrack() - The true north course of the vehicle in radians.

  • getSpeed() - The ground speed. This speed must not include vertical speed.

703.3 Units

Longitude and latitude are represented in radians, not degrees. This is consistent with the use of the Measurement object. Radians can be converted to degrees with the following formula, when lonlat is the longitude or latitude:

degrees = (lonlat / π) * 180

Calculation errors are significantly reduced when all calculations are done with a single unit system. This approach increases the complexity of presentation, but presentations are usually localized and require conversion anyway. Also, the radians are the units in the SI system and the java.lang.Math class uses only radians for angles.

703.4 Optimizations

A Position object must be immutable. It must remain its original values after it is created.

The Position class is not final. This approach implies that developers are allowed to sub-class it and provide optimized implementations. For example, it is possible that the Measurement objects are only constructed when actually requested.

703.5 Errors

Positioning information is never exact. Even large errors can exist in certain conditions. For this reason, the Position class returns all its measurements as Measurement objects. The Measurement class maintains an error value for each measurement.

In certain cases it is not possible to supply a value; in those cases, the method should return a NaN as specified in the Measurement class.

703.6 Using Position With Wire Admin

The primary reason the Position is specified, is to use it with the Wire Admin Service Specification. A bundle that needs position information should register a Consumer service and the configuration should connect this service to an appropriate Producer service.

703.7 Related Standards

703.7.1 JSR 179

In JCP, started [2] Location API for J2ME. This API is targeted at embedded systems and is likely to not contain some of the features found in this API. This API is targeted to be reviewed at Q4 of 2002. This API should be considered in a following release.

703.8 Security

The security aspects of the Position class are delegated to the security aspects of the Wire Admin service. The Position object only carries the information. The Wire Admin service will define what Consumer services will receive position information from what Producer services. It is therefore up to the administrator of the Wire Admin service to assure that only trusted bundles receive this information, or can supply it.

703.9 org.osgi.util.position

Version 1.0

Position Package Version 1.0.

Bundles wishing to use this package must list the package in the Import-Package header of the bundle's manifest.

Example import for consumers using the API in this package:

Import-Package: org.osgi.util.position; version="[1.0,2.0)"

703.9.1 Summary

  • Position - Position represents a geographic location, based on the WGS84 System (World Geodetic System 1984).

703.9.2 public class Position

Position represents a geographic location, based on the WGS84 System (World Geodetic System 1984).

The org.osgi.util.measurement.Measurement class is used to represent the values that make up a position.

A given position object may lack any of it's components, i.e. the altitude may not be known. Such missing values will be represented by null.

Position does not override the implementation of either equals() or hashCode() because it is not clear how missing values should be handled. It is up to the user of a position to determine how best to compare two position objects. A Position object is immutable.

Immutable

703.9.2.1 public Position(Measurement lat, Measurement lon, Measurement alt, Measurement speed, Measurement track)

a Measurement object specifying the latitude in radians, or null

a Measurement object specifying the longitude in radians, or null

a Measurement object specifying the altitude in meters, or null

a Measurement object specifying the speed in meters per second, or null

a Measurement object specifying the track in radians, or null

Constructs a Position object with the given values.

703.9.2.2 public Measurement getAltitude()

Returns the altitude of this position in meters.

a Measurement object in Unit.m representing the altitude in meters above the ellipsoid null if the altitude is not known.

703.9.2.3 public Measurement getLatitude()

Returns the latitude of this position in radians.

a Measurement object in Unit.rad representing the latitude, or null if the latitude is not known..

703.9.2.4 public Measurement getLongitude()

Returns the longitude of this position in radians.

a Measurement object in Unit.rad representing the longitude, or null if the longitude is not known.

703.9.2.5 public Measurement getSpeed()

Returns the ground speed of this position in meters per second.

a Measurement object in Unit.m_s representing the speed, or null if the speed is not known..

703.9.2.6 public Measurement getTrack()

Returns the track of this position in radians as a compass heading. The track is the extrapolation of previous previously measured positions to a future position.

a Measurement object in Unit.rad representing the track, or null if the track is not known..

703.10 References