javax.microedition.location
Class Coordinates

java.lang.Object
  |
  +--javax.microedition.location.Coordinates
Direct Known Subclasses:
QualifiedCoordinates

public class Coordinates
extends Object

The Coordinates class represents coordinates as latitude-longitude-altitude values. The latitude and longitude values are expressed in degrees using floating point values. The degrees are in decimal values (rather than minutes/seconds). The coordinates are given using the WGS84 datum.

This class also provides convenience methods for converting between a string coordinate representation and the double representation used in this class.

Since:
JDE 4.0.2

Field Summary
static int DD_MM
          Identifier for string coordinate representation Degrees, Minutes, decimal fractions of a minute
static int DD_MM_SS
          Identifier for string coordinate representation Degrees, Minutes, Seconds and decimal fractions of a second
 
Constructor Summary
Coordinates(double latitude, double longitude, float altitude)
          Constructs a new Coordinates object with the values specified.
 
Method Summary
 float azimuthTo(Coordinates to)
          Calculates the azimuth between the two points according to the ellipsoid model of WGS84.
static String convert(double coordinate, int outputType)
          Converts a double representation of a coordinate with decimal degrees into a string representation.
static double convert(String coordinate)
          Converts a String representation of a coordinate into the float representation as used in this API.
 float distance(Coordinates to)
          Calculates the geodetic distance between the two points according to the ellipsoid model of WGS84.
 float getAltitude()
          Returns the altitude component of this coordinate.
 double getLatitude()
          Returns the latitude component of this coordinate.
 double getLongitude()
          Returns the longitude component of this coordinate.
 void setAltitude(float altitude)
          Sets the geodetic altitude for this point.
 void setLatitude(double latitude)
          Sets the geodetic latitude for this point.
 void setLongitude(double longitude)
          Sets the geodetic longitude for this point.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

DD_MM

public static final int DD_MM
Identifier for string coordinate representation Degrees, Minutes, decimal fractions of a minute
Since:
JDE 4.0.2

DD_MM_SS

public static final int DD_MM_SS
Identifier for string coordinate representation Degrees, Minutes, Seconds and decimal fractions of a second
Since:
JDE 4.0.2
Constructor Detail

Coordinates

public Coordinates(double latitude,
                   double longitude,
                   float altitude)

Constructs a new Coordinates object with the values specified. The latitude and longitude parameters are expressed in degrees using floating point values. The degrees are in decimal values (rather than minutes/seconds).

The coordinate values always apply to the WGS84 datum.

The Float.NaN value can be used for altitude to indicate that altitude is not known.

Parameters:
latitude - the latitude of the location. Valid range: [-90.0, 90.0]. Positive values indicate northern latitude and negative values southern latitude.
longitude - the longitude of the location. Valid range: [-180.0, 180.0). Positive values indicate eastern longitude and negative values western longitude.
altitude - the altitude of the location in meters, defined as height above WGS84 ellipsoid. Float.NaN can be used to indicate that altitude is not known.
Throws:
IllegalArgumentException - if an input parameter is out of the valid range
Since:
JDE 4.0.2
Method Detail

azimuthTo

public float azimuthTo(Coordinates to)
Calculates the azimuth between the two points according to the ellipsoid model of WGS84. The azimuth is relative to true north. The Coordinates object on which this method is called is considered the origin for the calculation and the Coordinates object passed as a parameter is the destination which the azimuth is calculated to. When the origin is the North pole and the destination is not the North pole, this method returns 180.0. When the origin is the South pole and the destination is not the South pole, this method returns 0.0. If the origin is equal to the destination, this method returns 0.0. The implementation shall calculate the result as exactly as it can. However, it is required that the result is within 1 degree of the correct result.
Parameters:
to - the Coordinates of the destination
Returns:
the azimuth to the destination in degrees. Result is within the range [0.0 ,360.0).
Throws:
NullPointerException - if the parameter is null
Since:
JDE 4.0.2

convert

public static String convert(double coordinate,
                             int outputType)

Converts a double representation of a coordinate with decimal degrees into a string representation.

The string syntaxes supported are the same as for the convert(String) method. The implementation shall provide as many significant digits for the decimal fractions as are allowed by the string syntax definition.

Parameters:
coordinate - a double reprentation of a coordinate
outputType - identifier of the type of the string representation wanted for output. The constant DD_MM_SS identifies the syntax 1 and the constant DD_MM identifies the syntax 2.
Returns:
a string representation of the coordinate in a representation indicated by the parameter
Throws:
IllegalArgumentException - if the outputType is not one of the two costant values defined in this class or if the coordinate value is not within the range [-180.0, 180.0) or is Double.NaN
Since:
JDE 4.0.2
See Also:
convert(String)

convert

public static double convert(String coordinate)

Converts a String representation of a coordinate into the float representation as used in this API.

There are two string syntaxes supported:

1. Degrees, minutes, seconds and decimal fractions of seconds. This is expressed as a string complying with the following BNF definition where the degrees are within the range [-179, 179] and the minutes and seconds are within the range [0, 59], or the degrees is -180 and the minutes, seconds and decimal fractions are 0:

coordinate = degrees ":" minutes ":" seconds "." decimalfrac
              | degrees ":" minutes ":" seconds
              | degrees ":" minutes
degrees = degreedigits | "-" degreedigits
degreedigits = digit | nonzerodigit digit | "1" digit digit 
minutes = minsecfirstdigit digit
seconds = minsecfirstdigit digit
decimalfrac = 1*3digit 
digit = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9"
nonzerodigit = "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9"
minsecfirstdigit = "0" | "1" | "2" | "3" | "4" | "5" 
 

2. Degrees, minutes and decimal fractions of minutes. This is expressed as a string complying with the following BNF definition where the degrees are within the range [-179, 179] and the minutes are within the range [0, 59], or the degrees is -180 and the minutes and decimal fractions are 0:

coordinate = degrees ":" minutes "." decimalfrac
              | degrees ":" minutes
degrees = degreedigits | "-" degreedigits
degreedigits = digit | nonzerodigit digit | "1" digit digit 
minutes = minsecfirstdigit digit
decimalfrac = 1*5digit
digit = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9"
nonzerodigit = "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9"
minsecfirstdigit = "0" | "1" | "2" | "3" | "4" | "5" 

For example, for the double value of the coordinate 61.51d, the corresponding syntax 1 string is "61:30:36" and the corresponding syntax 2 string is "61:30.6"

Parameters:
coordinate - a String in either of the two representation specified above
Returns:
a double value with decimal degrees that matches the string representation given as the parameter
Throws:
IllegalArgumentException - if the coordinate input parameter does not comply with the defined syntax for the indicated type or if the inputType is not one of the two constant values defined in this class
NullPointerException - if the coordinate string is null
Since:
JDE 4.0.2

distance

public float distance(Coordinates to)

Calculates the geodetic distance between the two points according to the ellipsoid model of WGS84. Altitude is neglected from calculations.

The implementation shall calculate this as exactly as it can. However, it is required that the result is within 0.35% of the correct result.

Parameters:
to - the Coordinates of the destination
Returns:
the distance to the destination in meters
Throws:
NullPointerException - if the parameter is null
Since:
JDE 4.0.2

getAltitude

public float getAltitude()

Returns the altitude component of this coordinate. Altitude is defined to mean height above the WGS84 reference ellipsoid. 0.0 means a location at the ellipsoid surface, negative values mean the location is below the ellipsoid surface, Float.NaN that no altitude is available.

Returns:
the altitude in meters above the reference ellipsoid
Since:
JDE 4.0.2
See Also:
setAltitude(float)

getLatitude

public double getLatitude()

Returns the latitude component of this coordinate. Positive values indicate northern latitude and negative values southern latitude.

The latitude is given in WGS84 datum.

Returns:
the latitude in degrees
Since:
JDE 4.0.2
See Also:
setLatitude(double)

getLongitude

public double getLongitude()

Returns the longitude component of this coordinate. Positive values indicate eastern longitude and negative values western longitude.

The longitude is given in WGS84 datum.

Returns:
the longitude in degrees
Since:
JDE 4.0.2
See Also:
setLongitude(double)

setAltitude

public void setAltitude(float altitude)

Sets the geodetic altitude for this point.

Parameters:
altitude - the altitude of the location in meters, defined as height above the WGS84 ellipsoid. 0.0 means a location at the ellipsoid surface, negative values mean the location is below the ellipsoid surface, Float.NaN that no altitude is available
Since:
JDE 4.0.2
See Also:
getAltitude()

setLatitude

public void setLatitude(double latitude)

Sets the geodetic latitude for this point. Latitude is given as a double expressing the latitude in degrees in the WGS84 datum.

Parameters:
latitude - the latitude component of this location in degrees. Valid range: [-90.0, 90.0].
Throws:
IllegalArgumentException - if latitude is out of the valid range
Since:
JDE 4.0.2
See Also:
getLatitude()

setLongitude

public void setLongitude(double longitude)

Sets the geodetic longitude for this point. Longitude is given as a double expressing the longitude in degrees in the WGS84 datum.

Parameters:
longitude - the longitude of the location in degrees. Valid range: [-180.0, 180.0)
Throws:
IllegalArgumentException - if longitude is out of the valid range
Since:
JDE 4.0.2
See Also:
getLongitude()



Copyright 1999-2009 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Copyright 1993-2003 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.