javax.microedition.location
Class RectangleGeographicArea

java.lang.Object
  javax.microedition.location.GeographicArea
      javax.microedition.location.RectangleGeographicArea

public class RectangleGeographicArea
extends GeographicArea

This class represents a rectangular geographical area on WGS 84 Ellipsoid (see reference [WGS84]). Applications can use this object to request services from, for example, the MapServiceProvider.

A rectangle geographic area has a two pairs of sides that are parallel with each other. The pairs are orthogonal and aligned with the parallels and meridians. The boundary of the rectangle follows the surface of the earth.

This class is immutable. It means that if an application wants to modify the rectangle geographic area, it must instantiate a new object for the new area.

Since:

2.0

Constructor Summary

RectangleGeographicArea(Coordinates lowerLeftCorner, Coordinates upperRightCorner)
Constructs a RectangleGeographicArea object.

RectangleGeographicArea(double minLat, double maxLat, double minLon, double maxLon)
Constructs a RectangleGeographicArea object.

Method Summary

boolean	containsCoordinates(Coordinates coordinate) With this method an application can check if the given coordinate is inside this GeographicArea object.
boolean	equals(java.lang.Object obj) Overriding the equals method in Object class to compare the equality of values in two RectangleGeographicArea objects.
RectangleGeographicArea	getBoundingBox() Returns the RectangleGeographicArea object that surrounds this geographic area completely.
Coordinates	getCenterPoint() Returns the coordinates of the center point of this geographic area.
Coordinates[]	getCoordinates() Returns the two Coordinates objects that were used to construct this rectangle geographical area.
int	hashCode() Overriding the hashCode method in Object class.

Methods inherited from class java.lang.Object

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

Constructor Detail

RectangleGeographicArea

public RectangleGeographicArea(Coordinates lowerLeftCorner,
                               Coordinates upperRightCorner)

Constructs a RectangleGeographicArea object. The object is created as a rectangle from the given lowerLeftCorner and upperRightCorner coordinates. The coordinates are combined with lines that are aligned with parallels and meridians.

Creating the object always from the lowerLeftCorner to upperRightCorner allows also crossing the 180 longitude. Longitudes -180 and 180 denote the same longitude. If an application wants to create a rectangle that crosses the -180 longitude, it sets the longitude of lowerLeftCorner to a bigger value than the longitude of the upperRightCorner. This ensures that the rectangle is created with crossing the 180 longitude. Constructing an area with longitude of lowerLeftCorner -180 and longitude of upperRightCorner 180 must construct and area that goes around the earth.

Parameters:

lowerLeftCorner - coordinates of the lower left corner of the rectangle

upperRightCorner - coordinates of the upper right corner of the rectangle

Throws:

java.lang.IllegalArgumentException - if lowerLeftCorder.latitude > upperRightCorner.latitude

java.lang.NullPointerException - if lowerLeftCorner or upperRightCorner is null

RectangleGeographicArea

public RectangleGeographicArea(double minLat,
                               double maxLat,
                               double minLon,
                               double maxLon)

Constructs a RectangleGeographicArea object. The object is constructed as a rectangle from given parameter values. This method is the same as calling the other constructor with coordinates constructed from minLat, minLon pair and maxLat, maxLon pair. The valid values for minLat and maxLat are [-90.0, 90.0]. The valid values for minLon and maxLon are [-180.0, 180.0]. If minLon > maxLon the rectangle is created so that 180 longitude is crossed.

The API implementation constructs Coordinates objects from the parameter values and it must set the altitude to Float.NaN..

Parameters:

minLat - the minimum latitude of the rectangle area, valid range [-90.0, 90.0]

maxLat - the maximum latitude of the rectangle area, valid range [-90.0, 90.0]

minLon - the minimum longitude of the rectangle area, valid range [-180.0, 180.0]

maxLon - the maximum longitude of the rectangle area, valid range [-180.0, 180.0]

Throws:

java.lang.IllegalArgumentException - if minLat > maxLat or if an input parameter is out of the valid range

Method Detail

getCoordinates

public Coordinates[] getCoordinates()

Returns the two Coordinates objects that were used to construct this rectangle geographical area. First element in the returned array contains the lowerLeftCorner and the second element the upperRightCorner coordinates. If the constructor taking the double values is used, this method returns in the first element an Coordinates object constructed from minLat and minLon values. The second element contains a Coordinates object constructed from maxLat and maxLon values.

Returns:

the coordinates of the rectangular geographical area

containsCoordinates

public boolean containsCoordinates(Coordinates coordinate)

Description copied from class: GeographicArea

With this method an application can check if the given coordinate is inside this GeographicArea object. If the given coordinate is null, false is returned.

Specified by:

containsCoordinates in class GeographicArea

Parameters:

coordinate - a coordinates to be checked

Returns:

true, if the given point is inside this geographical area, else false

getCenterPoint

public Coordinates getCenterPoint()

Returns the coordinates of the center point of this geographic area.

The center point of the rectangle is the point with mean latitude and mean longitude.

Specified by:

getCenterPoint in class GeographicArea

Returns:

the center point coordinates of the area

getBoundingBox

public RectangleGeographicArea getBoundingBox()

Description copied from class: GeographicArea

Returns the RectangleGeographicArea object that surrounds this geographic area completely. This is the smallest rectangle that can be drawn around the area. If the area is bigger than what is allowed in WGS 84 coordinate system, the rectangle is truncated to valid WGS 84 coordinate values. The RectangeleGeographicArea is always aligned with parallels and meridians.

Specified by:

getBoundingBox in class GeographicArea

Returns:

a RectangleGeographicArea object containing this area

equals

public boolean equals(java.lang.Object obj)

Overriding the equals method in Object class to compare the equality of values in two RectangleGeographicArea objects.

Overrides:

equals in class java.lang.Object

Parameters:

obj - object to which the comparison is done

Returns:

true if all fields in the objects are equal, else false

hashCode

public int hashCode()

Overriding the hashCode method in Object class. The method returns a hash code value for the rectangle geographic area object. Two RectangleGeographicArea objects that are equal must have the same hash code. For more information see java.lang.Object.hashCode() method.

Overrides:

hashCode in class java.lang.Object

Returns:

the hash code of the rectangle geographic area