3.1.2.1 map_request Element

The <map_request> element has the following definition: 

<!ELEMENT map_request ((box | center | bounding_themes)?, srs?, legend?, themes?, styles?, geoFeature*)>
<!ELEMENT map_request ((box | center | bounding_themes)?, srs?, legend?, themes?, styles?, geoFeature*, north_arrow?)>

The root element of a map request to MapViewer is always named map_request.

  • <map_request> can have a child element that is <box> (see box Element), <center> (see center Element), or <bounding_themes> (see bounding_themes Element), which specifies the range of the user data to be plotted on a map. If none of these child elements is specified, the result map is drawn using all data available to MapViewer.
  • The optional <srs> child element is ignored by the current version of MapViewer.
  • The optional <legend> element (see legend Element) is used to draw a legend (map inset illustration) on top of a generated map, to make the visual aspects of the map more meaningful to users.
  • The optional <themes> element (see themes Element) specifies predefined or dynamically defined themes. The optional <styles> element (see styles Element) specifies dynamically defined styles.
  • The <geoFeature> element (see geoFeature Element) can be used to specify any number of individual geometries and their rendering attributes.
  • The optional <north_arrow> element (see north_arrow Element) is used to draw a north arrow marker based on the request rotation.

MapViewer first draws the themes defined in a base map (if a base map is specified as an attribute in the root element), then any user-provided themes, and finally any geoFeature elements.

Parent topic: Map Request DTD

3.1.2.1.1 map_request Attributes

The root element <map_request> has a number of attributes, some required and the others optional. The attributes are defined as follows: 

<!ATTLIST map_request
  datasource CDATA #REQUIRED
  srid CDATA #IMPLIED
  basemap CDATA #IMPLIED
  width CDATA #IMPLIED
  height CDATA #IMPLIED
  antialiasing (TRUE|FALSE) "FALSE"
  imagescaling (TRUE|FALSE) "TRUE"
  format (GIF|GIF_URL|GIF_STREAM|JAVA_IMAGE|
          PNG_STREAM|PNG_URL|PNG8_STREAM|PNG8_URL|
          JPEG_STREAM|JPEG_URL|PDF_STREAM|PDF_URL|
          SVG_STREAM|SVGZ_STREAM|SVGTINY_STREAM|
          SVG_URL|SVGZ_URL|SVGTINY_URL) "GIF_URL"
  transparent (TRUE|FALSE) "FALSE"
  title CDATA #IMPLIED
  title_style CDATA #IMPLIED
  footnote CDATA #IMPLIED
  footnote_style CDATA #IMPLIED
  rotation CDATA #IMPLIED*
  bgcolor (CDATA) "#A6CAF0"
  bgimage CDATA #IMPLIED
  zoomlevels CDATA #IMPLIED
  zoomfactor CDATA #IMPLIED
  zoomratio CDATA #IMPLIED
  initscale CDATA #IMPLIED
  navbar (TRUE|FALSE) "TRUE"
  infoon (TRUE|FALSE) "TRUE"
  onclick CDATA #IMPLIED
  onmousemove CDATA #IMPLIED
  rasterbasemap (TRUE|FALSE) "FALSE"
  onrectselect CDATA #IMPLIED
  onpolyselect CDATA #IMPLIED
  keepthemesorder CDATE #IMPLIED
  use_cached_basemap (TRUE|FALSE) "FALSE"
  snap_to_cache_scale (TRUE|FALSE) "FALSE"
  title_style CDATA #IMPLIED
  footnote CDATA #IMPLIED
  footnote_style CDATA #IMPLIED
  rotation CDATA #IMPLIED*
>

datasource is a required attribute that specifies a data source. A data source provides information to MapViewer about where to fetch the user data (and the mapping metadata) that is required to render a map.

srid is an optional attribute. If it is specified, it provides the SRID value of the coordinate system (spatial reference system) for the map request. If necessary, theme geometries will be converted to the specified coordinate system before being rendered, although geometries with an undefined coordinate system will not be converted. If this attribute is not specified, MapViewer uses the coordinate system of the first theme to be rendered as the coordinate system for the map request.

basemap is an optional attribute. When it is specified, MapViewer renders all themes that are specified for this base map. The definition of a base map is stored in the user's USER_SDO_MAPS view, as described in Section 2.9.3. Use this attribute if you will always need a background map on which to plot your own themes and geometry features.

width and height are optional attributes that together specify the size (in device units) of the resulting map image. This size is different from the size specified in the center element or box element, which is the range of the window into a user's source data. The default width and height values are 500 and 375 pixels, respectively. The unit is in pixels except for PDF formats, in which case pt is used as the unit, and the relationship with pixels is approximately 1 pt = 1.333 px (or, 1px = 0.75 pt). Thus, for example, if you request a map with size 500x375 "pt" in PDF format, this should generate an image of approximately 667x500 pixels.

antialiasing is an optional attribute. When its value is TRUE, MapViewer renders the map image in an antialiased manner. This usually provides a map with better graphic quality, but it may take longer for the map to be generated. The default value is FALSE (for faster map generation). (For backward compatibility, antialiase is a synonym for antialiasing, but you are encouraged to use antialiasing.)

imagescaling is an optional attribute. When its value is TRUE (the default), MapViewer attempts to scale the images to fit the current querying window and the generated map image size. When its value is FALSE, and if an image theme is included directly or indirectly (such as through a base map), the images from the image theme are displayed in their original resolution. This attribute has no effect when no image theme is involved in a map request.

format is an optional attribute that specifies the file format of the returned map image. The default value is GIF_URL, which is a URL to a GIF image stored on the MapViewer host system.
  • If you specify GIF, the generated GIF image data is embedded in a MapResponse object and returned to the client. If you specify GIF_STREAM, the generated image map content is returned directly to the client through the HTTP MIME type image/gif.
  • If you specify JAVA_IMAGE, a Java 2D BufferedImage object with a color model of TYPE_INT_RGB is embedded in a MapResponse object and returned to the client.
  • If you specify PNG_STREAM, the stream of the image in nonindexed PNG format is returned directly; if you specify PNG_URL, a URL to a nonindexed PNG image stored on the MapViewer host system is returned. (The PNG image format has some advantages over the GIF format, including faster image encoding and true color support.)
  • If you specify PNG8_STREAM, the stream of the image in indexed PNG format is returned directly; if you specify PNG8_URL, a URL to an indexed PNG image stored on the MapViewer host system is returned. (The PNG image format has some advantages over the GIF format, including faster image encoding and true color support. The indexed PNG format limits the total number of colors available for displaying the map to 256.)
  • If you specify JPEG_STREAM, the stream of the image in JPEG format is returned directly; if you specify JPEG_URL, a URL to a JPEG image stored on the MapViewer host system is returned.
  • If you specify PDF_STREAM, the stream of the image in PDF document format is returned directly; if you specify PDF_URL, a URL to a PDF document stored on the MapViewer host system is returned.
  • If you specify SVG_STREAM, the stream of the image in SVG Basic (SVGB) format is returned directly; if you specify SVG_URL, a URL to an SVG Basic image stored on the MapViewer host system is returned.
  • If you specify SVGZ_STREAM, the stream of the image in SVG Compressed (SVGZ) format is returned directly; if you specify SVGZ_URL, a URL to an SVG Compressed image stored on the MapViewer host system is returned. SVG Compressed format can effectively reduce the size of the SVG map by 40 to 70 percent compared with SVG Basic format, thus providing better performance.
  • If you specify SVGTINY_STREAM, the stream of the image in SVG Tiny (SVGT) format is returned directly; if you specify SVGTINY_URL, a URL to an SVG Tiny image stored on the MapViewer host system is returned. (The SVG Tiny format is designed for devices with limited display capabilities, such as cell phones.)

transparent is an optional attribute that applies to indexed PNG (PNG8_STREAM or PNG8_URL) formats only. When its value is TRUE, MapViewer makes the map background color completely transparent. The default value is FALSE.

title is an optional attribute that specifies the map title to be displayed on the top of the resulting map image.

title_style is an optional attribute that specifies the name of the text style to be used when rendering the title.

footnote is an optional attribute that specifies the footnote text to be added on the final map.

footnote_style is an optional attribute that specifies the name of the text style to be used when rendering the footnote.

bgcolor is an optional attribute that specifies the background color in the resulting map image. The default is water-blue (RGB value #A6CAF0). It must be specified as a hexadecimal value.

bgimage is an optional attribute that specifies the background image (GIF or JPEG format only) in the resulting map image. The image is retrieved at runtime when a map request is being processed, and it is rendered before any other map features, except that any bgcolor value is rendered before the background image.

zoomlevels is an optional attribute that specifies the number of zoom levels for an SVG map. The default is 4.

zoomfactor is an optional attribute that specifies the zoom factor for an SVG map. The zoom factor is the number by which to multiply the current zoom ratio for each integer increment (a zoomin operation) in the zoom level. The inverse of the zoomfactor value is used for each integer decrement (a zoomout operation) in the zoom level. For example, if the zoomfactor value is 2 (the default), zooming in from zoom level 4 to 5 will enlarge the detail by two; for example, if 1 inch of the map at zoom level 4 represents 10 miles, 1 inch of the map at zoom level 5 will represent 5 miles. The zoom ratio refers to the relative scale of the SVG map, which in its original size (zoom level 0) has a zoom ratio of 1.

zoomratio is an optional attribute that specifies the zoom ratio when an SVG map is initially displayed. The default value is 1, which is the original map size (zoom level 0). Higher zoom ratio values show the map zoomed in, and lower values show the map zoomed out.

initscale is an optional attribute that specifies the initial scale when an SVG map is first displayed. The default value is 1, which is the original map size (zoom level 0). Higher values will show the SVG map zoomed in when it is first displayed.

navbar is an optional attribute that specifies whether to display the built-in navigation bar on an SVG map. If its value is TRUE (the default), the navigation bar is displayed; if it is set to FALSE, the navigation bar is not displayed.

infoon is an optional attribute that specifies whether to display hidden information when the mouse moves over features for which hidden information is provided. If its value is TRUE (the default), hidden information is displayed when the mouse moves over such features; if it is set to FALSE, hidden information is not displayed when the mouse moves over such features. Regardless of the value, however, hidden information is always rendered in an SVG map; this attribute only controls whether hidden information can be displayed. (To specify the hidden information for a feature, use the hidden_info attribute in the <geoFeature> element, as explained in Section 3.1.2.5.)

onclick is an optional attribute that specifies the name of the JavaScript function to be called when a user clicks on an SVG map. The JavaScript function must be defined in the HTML document outside the SVG definition. This function must accept two parameters: x and y, which specify the coordinates inside the SVG window where the click occurred. The coordinates are defined in the local SVG window coordinate system, which starts at (0, 0) at the upper-left corner and ends at (width, height) at the lower-right corner. For information about using JavaScript functions with SVG maps, see Appendix B.

onmousemove is an optional attribute that specifies the name of the JavaScript function to be called when a user moves the mouse on an SVG map. The JavaScript function must be defined in the HTML document outside the SVG definition. This function must accept two parameters: x and y, which specify the coordinates inside the SVG window where the move occurred. The coordinates are defined in the local SVG window coordinate system, which starts at (0, 0) at the upper-left corner and ends at (width, height) at the lower-right corner. For information about using JavaScript functions with SVG maps, see Appendix B.

rasterbasemap is an optional attribute. If the map format is SVG and the value of this attribute is TRUE, MapViewer renders the base map as a raster image. In this case, the base map image becomes the background image for the SVG map, and all other vector features are rendered on top of it.

onrectselect is an optional attribute that specifies the name of the JavaScript function to be called when a user draws a rectangular selection area by clicking and dragging the mouse (to indicate two diagonally opposite corners) on an SVG map. The JavaScript function must be defined in the HTML document outside the SVG definition. This function must not accept any parameters. For information about using JavaScript functions with SVG maps, see Appendix B.

onpolyselect is an optional attribute that specifies the name of the JavaScript function to be called when a user draws a polygon-shaped selection area by clicking and dragging the mouse (to indicate more than two vertices) on an SVG map. The JavaScript function must be defined in the HTML document outside the SVG definition. This function must not accept any parameters. For information about using JavaScript functions with SVG maps, see Appendix B.

keepthemesorder is an optional attribute. If the map format is not SVG and the value of this attribute is TRUE, MapViewer always renders the themes in the order specified in the map request; if the value of this attribute is FALSE, raster themes will be rendered before vector themes.

use_cached_basemap is an optional attribute. If the value of this attribute is TRUE and if a map tile layer caches the same base map specified by the basemap attribute, MapViewer tries to use the map images cached by the map tile server to render the map specified by the map request. For information about the map tile server, see Section 3.3.

snap_to_cache_scale is an optional attribute that is effective only when the use_cached_basemap attribute value is TRUE. It affects the behavior of MapViewer only when the map scale specified by the map request does not match that of any predefined cached zoom level. If this attribute is FALSE, MapViewer uses the cached map images to render the base map only when the map scale specified by the map request matches the scale of a cached predefined zoom level. If this attribute is TRUE, MapViewer always uses the cached map images to render the base map and adjusts the map scale to fit that of a cached predefined zoom level when the request map scale does not match any of the cached predefined zoom levels.

title_style is an optional attribute that defines the text style to be used for the title. footnote is an optional attribute that defines the text for a footnote to be added to the map.

footnote_style is an optional attribute that defines the text style to be used for the footnote text.

rotation is an optional attribute defined in degrees to apply a rotation on the map. Positive values means counterclockwise rotation of the map. Rotation values are ignored if the request does not have a window defined (no center and size defined, or using bounding themes). Rotation is not supported for requests using base maps coming from the Oracle Maps cache.

Parent topic: map_request Element