javax.microedition.location
Class PolygonGeographicArea

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

public class PolygonGeographicArea
extends GeographicArea

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

A polygon geographic area has an array of coordinates that are the corners of the polygon. The polygon area is constructed by combining the corner points with the shortest path on the WGS 84 Ellipsoid starting from the first element in the array. The last path is drawn from the last element in the array to the first element to form a closed shape. The boundaries of the polygon follow the surface of the earth.

This specification only supports creation of simple polygons. It means that the sides of the polygon do not intersect. If an application needs to use complex polygons, they can be represented with multiple simple polygons. The following figure illustrated simple and complex polygons.

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

Since:

2.0

Constructor Summary

PolygonGeographicArea(Coordinates[] coordinates)
Constructs a PolygonGeographicArea 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 PolygonGeographicArea 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 an array of Coordinates objects that form the polygonal 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

PolygonGeographicArea

public PolygonGeographicArea(Coordinates[] coordinates)

Constructs a PolygonGeographicArea object. The polygonal area is constructed by combining the corner points with the shortest path on the WGS 84 Ellipsoid starting from the first element in the array. The last path is drawn from the last element in the array to the first element to form a closed shape by the API implementation.

The polygon area can not contain polar areas. This restriction is needed because the bounding box of the polygon crossing polar areas can not be represented with RectangleGeographicArea. The polygon area must therefore be formed as the area that does not contain polar areas of the two possible areas that the given polyline defines. If the given coordinates from an area that contains one of the polar areas, an IllegalArgumentException if thrown.

This specification only supports simple polygons, meaning polygons whose sides do not intersect. If the input array contains coordinates that form a complex polygon (sides intersect) an IllegalArgumentException is thrown. Complex polygon can always be represented with multiple simple polygons.

Parameters:

coordinates - coordinates that form the polygon geographic area

Throws:

java.lang.IllegalArgumentException - if coordinates is an empty array or if coordinates array forms a complex polygon or if the area contains polar areas

java.lang.NullPointerException - if coordinates is null or if coordinates array contains null elements

Method Detail

getCoordinates

public Coordinates[] getCoordinates()

Returns an array of Coordinates objects that form the polygonal geographical area. The coordinates form a round trip around the area and These coordinates have been given in the constructor.

Returns:

the coordinates of the polygon 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

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

getCenterPoint

public Coordinates getCenterPoint()

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

The center point of the polygon with more than 3 vertices is the center point of the longest diagonal. For a triangle this method returns the intersection of the triangle medians. A median is the line from a vertex to the midpoint of the opposite side. If the polygon is a line, the center point is the mid point of the line. For a point polygon, the point itself is returned. The center point may be outside the polygon.

Specified by:

getCenterPoint in class GeographicArea

Returns:

the center point coordinates of the area

equals

public boolean equals(java.lang.Object obj)

Overriding the equals method in Object class to compare the equality of values in two PolygonGeographicArea objects. The coordinates array that forms the polygon area (retrieved with getCoordinates method) may start from a different coordinate in two different instances. However as long as the order of the coordinates remains the same they both form the same polygon area. For example, coordinates c1, c2 and c3 form the same area as coordinates c2, c3 and c1. If the starting point of the polygon is different but they still contain equal set of coordinates in the same order, this method must return true.

Overrides:

equals in class java.lang.Object

Parameters:

obj - object to which the comparison is done

Returns:

true if 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 polygon geographic area object. Two PolygonGeographicArea 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 polygon geographic area