oracle.panama.spatial.mapper
Interface Mapper

public interface Mapper

This interface describes the functionality of any mapping provider. Fundamentally, the user can request maps with single points, lists of points, routes or single maneuvers marked. The area of interest can be determined in two ways: It can be specified as minimum and maximum of latitude and longitude. Alternatively, it is automatically inferred as the minimum bounding box of all marked points. In either case, the actual map image can not possibly cover exactly the bounding box. The reason is that the bounding box is rectangular in the used geographic coordinate system (using latitude and longitude). Most map visualizations are, however, rectangular in a projected coordinate system. If a rectangular bounding box is transformed from a geographic coordinate system to a projected one, it becomes non-rectangular. It then has to be approximated by a rectangle to result in a rectangular map image. Such an approximation can only be done well, if the projected coordinate system and the scaling method of the mapping provider are known exactly. This does typically not apply, because the mapping provider is external. Subsequently, the map image will probably include some buffer margin around the requested bounding box. Finally, a single map image can be requested or a matrix of segments of this map. Because of the previously mentioned buffer margin the segments will show some overlap. The overlap can not be quantified exactly because of imperfect knowledge regarding the projected coordinate system used by the external mapping provider. A segmented map image can be useful for distributing a map over several screens on devices with small displays. The user of a cell phone can then switch between the segments.

Method Summary

Type	Method
java.lang.String	getMapURL(Maneuver man, boolean allowTurning) This function returns a URL String to a map image file visualizing a maneuver.
java.lang.String	getMapURL(Point[] locations, ImageFormats fileType, double minLon, double maxLon, double minLat, double maxLat, int width, int height, boolean allowTurning) This function returns a URL String to a map image file visualizing a list of Point objects.
java.lang.String	getMapURL(Point[] locations, ImageFormats fileType, int width, int height, boolean allowTurning) This function returns a URL String to a map image file visualizing a list of Point objects.
java.lang.String	getMapURL(Point location, ImageFormats fileType, double minLon, double maxLon, double minLat, double maxLat, int width, int height, boolean allowTurning) This function returns a URL String to a map image file visualizing a Point object.
java.lang.String	getMapURL(Point location, ImageFormats fileType, int width, int height, boolean allowTurning) This function returns a URL String to a map image file visualizing a Point object.
java.lang.String	getMapURL(RoutingResult route, boolean allowTurning) This function returns a URL String to a map image file visualizing a route.
java.lang.String[][]	getMapURLs(Maneuver man, int subdivisionLevel, boolean allowTurning) This function returns a matrix of URL Strings to segments of a map image visualizing a maneuver.
java.lang.String[][]	getMapURLs(Point[] locations, ImageFormats fileType, double minLon, double maxLon, double minLat, double maxLat, int width, int height, int subdivisionLevel, boolean allowTurning) This function returns a matrix of URL Strings to segments of a map image visualizing a list of Point objects.
java.lang.String[][]	getMapURLs(Point[] locations, ImageFormats fileType, int width, int height, int subdivisionLevel, boolean allowTurning) This function returns a matrix of URL Strings to segments of a map image visualizing a list of Point objects.
java.lang.String[][]	getMapURLs(Point location, ImageFormats fileType, double minLon, double maxLon, double minLat, double maxLat, int width, int height, int subdivisionLevel, boolean allowTurning) This function returns a matrix of URL Strings to segments of a map image visualizing a Point object.
java.lang.String[][]	getMapURLs(Point location, ImageFormats fileType, int width, int height, int subdivisionLevel, boolean allowTurning) This function returns a matrix of URL Strings to segments of a map image visualizing a Point object.
java.lang.String[][]	getMapURLs(RoutingResult route, int subdivisionLevel, boolean allowTurning) This function returns a matrix of URL Strings to segments of a map image visualizing a route.
java.lang.String	xmlMap(org.w3c.dom.Document xmlRequest) This function performs mapping based on an XML request (eLocation XML).

Method Detail

getMapURL

public java.lang.String getMapURL(Point[] locations,
                                  ImageFormats fileType,
                                  int width,
                                  int height,
                                  boolean allowTurning)

This function returns a URL String to a map image file visualizing a list of Point objects. The area of interest is automatically inferred to be the minimum bounding box of the specified Point objects. This function IS NOT TO BE implemented by any provider proxy. It is performed by the framework itself and translated to other functions.

Parameters:

locations - an array of Point objects that should be marked on the map, including respective labels

fileType - an ImageFormats object representing the image format required (such as GIF)

width - an int representing the map width in pixels

height - an int representing the map height in pixels

allowTurning - a boolean representing whether it is allowed to turn the map by 90 degrees against the clock, if the map can then better match the aspect ratio of the area of interest. California can be displayed better on a tall map than a wide one. If the device display is wide and we allow for turning it, then turning the image results in a better map.

Returns:

a String representing the URL of the map

getMapURL

public java.lang.String getMapURL(Point location,
                                  ImageFormats fileType,
                                  int width,
                                  int height,
                                  boolean allowTurning)

This function returns a URL String to a map image file visualizing a Point object. The area of interest is automatically inferred to be a small bounding box around the specified Point object. This function IS NOT TO BE implemented by any provider proxy. It is performed by the framework itself and translated to other functions.

Parameters:

location - a Point object that should be marked on the map, including label

fileType - an ImageFormats object representing the image format required (such as GIF)

width - an int representing the map width in pixels

height - an int representing the map height in pixels

allowTurning - a boolean representing whether it is allowed to turn the map by 90 degrees against the clock, if the map can then better match the aspect ratio of the area of interest. California can be displayed better on a tall map than a wide one. If the device display is wide and we allow for turning it, then turning the image results in a better map.

Returns:

a String representing the URL of the map

getMapURL

public java.lang.String getMapURL(RoutingResult route,
                                  boolean allowTurning)

This function returns a URL String to a map image file visualizing a route. The area of interest is decided by the routing provider. The provider is assumed to make a reasonable decision based on the locations of start and end points. The image format is decided by the routing provider. The width and height of the map image have been previously defined in the RoutingSettings object passed to the routing service. This function IS NOT TO BE implemented by any provider proxy. It is performed by the framework itself and translated to other functions.

Parameters:

route - a RoutingResult object to display on the map

allowTurning - a boolean representing whether it is allowed to turn the map by 90 degrees against the clock, if the map can then better match the aspect ratio of the area of interest. California can be displayed better on a tall map than a wide one. If the device display is wide and we allow for turning it, then turning the image results in a better map.

Returns:

a String representing the URL of the map

getMapURL

public java.lang.String getMapURL(Maneuver man,
                                  boolean allowTurning)

This function returns a URL String to a map image file visualizing a maneuver. The area of interest is decided by the routing provider. The provider is assumed to make a reasonable decision based on the locations of start and end points. The image format is decided by the routing provider. The width and height of the map image have been previously defined in the RoutingSettings object passed to the routing service. This function IS NOT TO BE implemented by any provider proxy. It is performed by the framework itself and translated to other functions.

Parameters:

man - a Maneuver object to display on the map

allowTurning - a boolean representing whether it is allowed to turn the map by 90 degrees against the clock, if the map can then better match the aspect ratio of the area of interest. California can be displayed better on a tall map than a wide one. If the device display is wide and we allow for turning it, then turning the image results in a better map.

Returns:

a String representing the URL of the map

getMapURL

public java.lang.String getMapURL(Point[] locations,
                                  ImageFormats fileType,
                                  double minLon,
                                  double maxLon,
                                  double minLat,
                                  double maxLat,
                                  int width,
                                  int height,
                                  boolean allowTurning)

This function returns a URL String to a map image file visualizing a list of Point objects. The area of interest has to be specified by a bounding box. This function MUST be implemented by each provider proxy. It is part of the required core functionality. Any provider not supporting this function might have serious restrictions in supporting any reasonable application. At the very least, such a "lacking" provider proxy could not be used as a "primary" provider. However, fail-over guarantees that applications would work if this function is covered by at least one provider proxy.

Parameters:

locations - an array of Point objects that should be marked on the map, including respective labels

fileType - an ImageFormats object representing the image format required (such as GIF)

minLon - a double representing the minimum longitude to define the upper and lower left corners of the area of interest

maxLon - a double representing the maximum longitude to define the upper and lower right corners of the area of interest

minLat - a double representing the minimum latitude to define the lower left and right corners of the area of interest

maxLat - a double representing the maximum latitude to define the upper left and right corners of the area of interest

width - an int representing the map width in pixels

height - an int representing the map height in pixels

allowTurning - a boolean representing whether it is allowed to turn the map by 90 degrees against the clock, if the map can then better match the aspect ratio of the area of interest. California can be displayed better on a tall map than a wide one. If the device display is wide and we allow for turning it, then turning the image results in a better map.

Returns:

a String representing the URL of the map

getMapURL

public java.lang.String getMapURL(Point location,
                                  ImageFormats fileType,
                                  double minLon,
                                  double maxLon,
                                  double minLat,
                                  double maxLat,
                                  int width,
                                  int height,
                                  boolean allowTurning)

This function returns a URL String to a map image file visualizing a Point object. The area of interest has to be specified by a bounding box. This function IS NOT TO BE implemented by any provider proxy. It is performed by the framework itself and translated to other functions.

Parameters:

location - a Point object that should be marked on the map, including label

fileType - an ImageFormats object representing the image format required (such as GIF)

minLon - a double representing the minimum longitude to define the upper and lower left corners of the area of interest

maxLon - a double representing the maximum longitude to define the upper and lower right corners of the area of interest

minLat - a double representing the minimum latitude to define the lower left and right corners of the area of interest

maxLat - a double representing the maximum latitude to define the upper left and right corners of the area of interest

width - an int representing the map width in pixels

height - an int representing the map height in pixels

allowTurning - a boolean representing whether it is allowed to turn the map by 90 degrees against the clock, if the map can then better match the aspect ratio of the area of interest. California can be displayed better on a tall map than a wide one. If the device display is wide and we allow for turning it, then turning the image results in a better map.

Returns:

a String representing the URL of the map

getMapURLs

public java.lang.String[][] getMapURLs(Point[] locations,
                                       ImageFormats fileType,
                                       int width,
                                       int height,
                                       int subdivisionLevel,
                                       boolean allowTurning)

This function returns a matrix of URL Strings to segments of a map image visualizing a list of Point objects. The area of interest is automatically inferred to be the minimum bounding box of the specified Point objects. This function IS NOT TO BE implemented by any provider proxy. It is performed by the framework itself and translated to other functions.

Parameters:

locations - an array of Point objects that should be marked on the map, including respective labels

fileType - an ImageFormats object representing the image format required (such as GIF)

width - an int representing the map width in pixels

height - an int representing the map height in pixels

subdivisionLevel - An int to represent the level of subdivisioning of the complete map in segments. Levels 0, 1, 2, 3, 4, 5 result in 1x1, 2x2, 4x4, 8x8, 16x16, 32x32 segments. Using this regular subdivisioning scheme, there is a problem if the aspect ratios of the area of interest and the map image differ considerably. If a horizontally long and thin area of interest is mapped on a square map image, an increased vertical buffer will result. All these vertical buffers of neighboring segments will overlap. To reduce the vertical overlap of segment map images, the implementation of this interface may choose to use less segments vertically. For example 4x2 segments might have less overlap than 4x4 segments of the same area.

allowTurning - a boolean representing whether it is allowed to turn the map by 90 degrees against the clock, if the map can then better match the aspect ratio of the area of interest. California can be displayed better on a tall map than a wide one. If the device display is wide and we allow for turning it, then turning the image results in a better map.

Returns:

an array of arrays of Strings representing the URLs of the map segments

getMapURLs

public java.lang.String[][] getMapURLs(Point[] locations,
                                       ImageFormats fileType,
                                       double minLon,
                                       double maxLon,
                                       double minLat,
                                       double maxLat,
                                       int width,
                                       int height,
                                       int subdivisionLevel,
                                       boolean allowTurning)

This function returns a matrix of URL Strings to segments of a map image visualizing a list of Point objects. The area of interest is automatically inferred to be the minimum bounding box of the specified Point objects. This function IS NOT TO BE implemented by any provider proxy. It is performed by the framework itself and translated to other functions.

Parameters:

locations - an array of Point objects that should be marked on the map, including respective labels

fileType - an ImageFormats object representing the image format required (such as GIF)

minLon - a double representing the minimum longitude to define the upper and lower left corners of the area of interest

maxLon - a double representing the maximum longitude to define the upper and lower right corners of the area of interest

minLat - a double representing the minimum latitude to define the lower left and right corners of the area of interest

maxLat - a double representing the maximum latitude to define the upper left and right corners of the area of interest

width - an int representing the map width in pixels

height - an int representing the map height in pixels

subdivisionLevel - An int to represent the level of subdivisioning of the complete map in segments. Levels 0, 1, 2, 3, 4, 5 result in 1x1, 2x2, 4x4, 8x8, 16x16, 32x32 segments. Using this regular subdivisioning scheme, there is a problem if the aspect ratios of the area of interest and the map image differ considerably. If a horizontally long and thin area of interest is mapped on a square map image, an increased vertical buffer will result. All these vertical buffers of neighboring segments will overlap. To reduce the vertical overlap of segment map images, the implementation of this interface may choose to use less segments vertically. For example 4x2 segments might have less overlap than 4x4 segments of the same area.

allowTurning - a boolean representing whether it is allowed to turn the map by 90 degrees against the clock, if the map can then better match the aspect ratio of the area of interest. California can be displayed better on a tall map than a wide one. If the device display is wide and we allow for turning it, then turning the image results in a better map.

Returns:

an array of arrays of Strings representing the URLs of the map segments

getMapURLs

public java.lang.String[][] getMapURLs(Point location,
                                       ImageFormats fileType,
                                       int width,
                                       int height,
                                       int subdivisionLevel,
                                       boolean allowTurning)

This function returns a matrix of URL Strings to segments of a map image visualizing a Point object. The area of interest is automatically inferred to be a small bounding box around the specified Point object. This function IS NOT TO BE implemented by any provider proxy. It is performed by the framework itself and translated to other functions.

Parameters:

location - a Point object that should be marked on the map, including label

fileType - an ImageFormats object representing the image format required (such as GIF)

width - an int representing the map width in pixels

height - an int representing the map height in pixels

subdivisionLevel - An int to represent the level of subdivisioning of the complete map in segments. Levels 0, 1, 2, 3, 4, 5 result in 1x1, 2x2, 4x4, 8x8, 16x16, 32x32 segments. Using this regular subdivisioning scheme, there is a problem if the aspect ratios of the area of interest and the map image differ considerably. If a horizontally long and thin area of interest is mapped on a square map image, an increased vertical buffer will result. All these vertical buffers of neighboring segments will overlap. To reduce the vertical overlap of segment map images, the implementation of this interface may choose to use less segments vertically. For example 4x2 segments might have less overlap than 4x4 segments of the same area.

allowTurning - a boolean representing whether it is allowed to turn the map by 90 degrees against the clock, if the map can then better match the aspect ratio of the area of interest. California can be displayed better on a tall map than a wide one. If the device display is wide and we allow for turning it, then turning the image results in a better map.

Returns:

an array of arrays of Strings representing the URLs of the map segments

getMapURLs

public java.lang.String[][] getMapURLs(Point location,
                                       ImageFormats fileType,
                                       double minLon,
                                       double maxLon,
                                       double minLat,
                                       double maxLat,
                                       int width,
                                       int height,
                                       int subdivisionLevel,
                                       boolean allowTurning)

This function returns a matrix of URL Strings to segments of a map image visualizing a Point object. The area of interest is automatically inferred to be a small bounding box around the specified Point object. This function IS NOT TO BE implemented by any provider proxy. It is performed by the framework itself and translated to other functions.

Parameters:

location - a Point object that should be marked on the map, including label

fileType - an ImageFormats object representing the image format required (such as GIF)

minLon - a double representing the minimum longitude to define the upper and lower left corners of the area of interest

maxLon - a double representing the maximum longitude to define the upper and lower right corners of the area of interest

minLat - a double representing the minimum latitude to define the lower left and right corners of the area of interest

maxLat - a double representing the maximum latitude to define the upper left and right corners of the area of interest

width - an int representing the map width in pixels

height - an int representing the map height in pixels

subdivisionLevel - An int to represent the level of subdivisioning of the complete map in segments. Levels 0, 1, 2, 3, 4, 5 result in 1x1, 2x2, 4x4, 8x8, 16x16, 32x32 segments. Using this regular subdivisioning scheme, there is a problem if the aspect ratios of the area of interest and the map image differ considerably. If a horizontally long and thin area of interest is mapped on a square map image, an increased vertical buffer will result. All these vertical buffers of neighboring segments will overlap. To reduce the vertical overlap of segment map images, the implementation of this interface may choose to use less segments vertically. For example 4x2 segments might have less overlap than 4x4 segments of the same area.

allowTurning - a boolean representing whether it is allowed to turn the map by 90 degrees against the clock, if the map can then better match the aspect ratio of the area of interest. California can be displayed better on a tall map than a wide one. If the device display is wide and we allow for turning it, then turning the image results in a better map.

Returns:

an array of arrays of Strings representing the URLs of the map segments

getMapURLs

public java.lang.String[][] getMapURLs(RoutingResult route,
                                       int subdivisionLevel,
                                       boolean allowTurning)

This function returns a matrix of URL Strings to segments of a map image visualizing a route. The area of interest is decided by the routing provider. The provider is assumed to make a reasonable decision based on the locations of start and end points. The image format is decided by the routing provider. The width and height of the map image have been previously defined in the RoutingSettings object passed to the routing service. This function IS NOT TO BE implemented by any provider proxy. It is performed by the framework itself and translated to other functions.

Parameters:

route - a RoutingResult object to display on the map

subdivisionLevel - An int to represent the level of subdivisioning of the complete map in segments. Levels 0, 1, 2, 3, 4, 5 result in 1x1, 2x2, 4x4, 8x8, 16x16, 32x32 segments. Using this regular subdivisioning scheme, there is a problem if the aspect ratios of the area of interest and the map image differ considerably. If a horizontally long and thin area of interest is mapped on a square map image, an increased vertical buffer will result. All these vertical buffers of neighboring segments will overlap. To reduce the vertical overlap of segment map images, the implementation of this interface may choose to use less segments vertically. For example 4x2 segments might have less overlap than 4x4 segments of the same area.

allowTurning - a boolean representing whether it is allowed to turn the map by 90 degrees against the clock, if the map can then better match the aspect ratio of the area of interest. California can be displayed better on a tall map than a wide one. If the device display is wide and we allow for turning it, then turning the image results in a better map.

Returns:

an array of arrays of Strings representing the URLs of the map segments

getMapURLs

public java.lang.String[][] getMapURLs(Maneuver man,
                                       int subdivisionLevel,
                                       boolean allowTurning)

This function returns a matrix of URL Strings to segments of a map image visualizing a maneuver. The area of interest is decided by the routing provider. The provider is assumed to make a reasonable decision based on the locations of start and end points. The image format is decided by the routing provider. The width and height of the map image have been previously defined in the RoutingSettings object passed to the routing service. This function IS NOT TO BE implemented by any provider proxy. It is performed by the framework itself and translated to other functions.

Parameters:

man - a Maneuver object to display on the map

subdivisionLevel - An int to represent the level of subdivisioning of the complete map in segments. Levels 0, 1, 2, 3, 4, 5 result in 1x1, 2x2, 4x4, 8x8, 16x16, 32x32 segments. Using this regular subdivisioning scheme, there is a problem if the aspect ratios of the area of interest and the map image differ considerably. If a horizontally long and thin area of interest is mapped on a square map image, an increased vertical buffer will result. All these vertical buffers of neighboring segments will overlap. To reduce the vertical overlap of segment map images, the implementation of this interface may choose to use less segments vertically. For example 4x2 segments might have less overlap than 4x4 segments of the same area.

allowTurning - a boolean representing whether it is allowed to turn the map by 90 degrees against the clock, if the map can then better match the aspect ratio of the area of interest. California can be displayed better on a tall map than a wide one. If the device display is wide and we allow for turning it, then turning the image results in a better map.

Returns:

an array of arrays of Strings representing the URLs of the map segments

xmlMap

public java.lang.String xmlMap(org.w3c.dom.Document xmlRequest)

This function performs mapping based on an XML request (eLocation XML). This function IS NOT TO BE implemented by any provider proxy. It is performed by the framework itself and translated to other functions.

Parameters:

xmlRequest - a Document object representing the XMl document of the mapping request.

Returns:

a String representing the XMl String of the mapping response.