3 MapViewer Map Request XML API
This chapter explains how to submit map requests in XML format to MapViewer, and it describes the XML document type definitions (DTDs) for the map requests (input) and responses (output). XML is widely used for transmitting structured documents using the HTTP protocol. If an HTTP request (GET or POST method) is used, it is assumed the request has a parameter named xml_request whose value is a string containing the XML document for the request.
(In addition to map requests, the MapViewer XML API can be used for administrative requests, such as adding new data sources. Administrative requests are described in Chapter 7.)
As shown in Figure 1-1 in Section 1.1.1, the basic flow of action with MapViewer is that a client locates a remote MapViewer instance, binds to it, sends a map request, and processes the map response returned by the MapViewer instance.
A request to the MapViewer servlet has the following format:
http://hostname[:port]/MapViewer-servlet-path?xml_request=xml-request
In this format:
-
hostnameis the network path of the server on which MapViewer is running. -
portis the port on which the Web server listens. -
MapViewer-servlet-pathis the MapViewer servlet path (for example,mapviewer/omserver). -
xml-requestis the URL-encoded XML request submitted using the HTMLGETorPOSTmethod.
The input XML is required for all requests. The output depends on the content of the request: the response can be either an XML document, or a binary object containing the (generated image) file requested by the user.
In an input request, you must specify a data source, and you can specify one or more of the following:
-
Themes and styles.
-
A center point or a box for the map display, and options such as highlight, label, and styles.
-
A predefined base map, which can be reused and overlaid with custom data.
-
A custom theme with the user data points (or any geometry) retrieved dynamically and plotted directly from an accessible database.
-
Custom features (point, circles, or any geometry) specified in the XML request string to be plotted. These require that you provide the dynamic data in the format of the
<geoFeature>element (described in Section 3.2.5), as defined in the DTD. The geometry portion of the<geoFeature>element adopts the Geometry DTD as specified in Open GIS Consortium Geography Markup Language Version 1.0 (OGC GML v1.0). -
Thematic mapping.
You can manage the definition of base maps, themes, and styles (individual symbologies) using the Map Builder tool, which is described in Chapter 9.
For the current release, MapViewer accepts only a coordinate pair to identify the location for a map request; it cannot take a postal address as direct input for a map.
This chapter first presents some examples of map requests (see Section 3.1), and then presents detailed explanations of the following XML DTDs for requests and other operations:
3.1 Map Request Examples
This section provides examples of map requests. It refers to concepts, elements, and attributes that are explained in detail in Section 3.2. It contains sections with the following examples:
-
Section 3.1.3, "Map Request with Base Map, Center, and Additional Predefined Theme"
-
Section 3.1.4, "Map Request with Center, Base Map, Dynamically Defined Theme, and Other Features"
-
Section 3.1.8, "Map Request with SRID Different from Data SRID"
3.1.1 Simple Map Request
Example 3-1 is a very simple map request. It requests a map consisting of a blank blue image (from the mvdemo data source) with the string Hello World drawn on top. (The datasource attribute is required for a map request, even though this specific map request does not retrieve any map data from the data source.)
3.1.2 Map Request with Dynamically Defined Theme
Example 3-2 is a simple map request with one dynamically defined theme. It requests a map of all Oracle Spatial geometries from the COUNTIES table.
Example 3-2 Simple Map Request with a Dynamically Defined Theme
<?xml version="1.0" encoding="UTF-8" ?>
<map_request datasource="lbs_data">
<themes>
<theme name="t1">
<jdbc_query spatial_column = "GEOM"
datasource = "lbs_data">
SELECT geom FROM counties
</jdbc_query>
</theme>
</themes>
</map_request>
3.1.3 Map Request with Base Map, Center, and Additional Predefined Theme
Example 3-3 requests a map with a specified center for the result map, and specifies a predefined theme (poi_theme_us_restaurants) to be rendered in addition to the predefined themes that are part of the base map (basemap="us_base").
Example 3-3 Map Request with Base Map, Center, and Additional Predefined Theme
<?xml version="1.0" encoding="UTF-8" ?>
<map_request datasource="lbs_data" title="LBS CUSTOMER MAP"
basemap="us_base" width="500" height="375"
bgcolor="#a6cae0" format="GIF_URL">
<center size="1">
<geoFeature typeName="mapcenter" label="Motel 1" text_style="T.MOTEL"
render_style="M.MOTEL" radius="300">
<geometricProperty>
<Point>
<coordinates>-122.2615, 37.5266</coordinates>
</Point>
</geometricProperty>
</geoFeature>
</center>
<srs>SDO:8265</srs>
<themes>
<theme name="poi_theme_us_restaurants"/>
</themes>
</map_request>
Notes on Example 3-3:
-
Because
basemapis specified, MapViewer first draws all predefined themes for that base map before drawing the specified theme (poi_theme_us_restaurants). -
The center will be drawn with a marker of the
M.MOTELstyle and the labelMotel 1in theT.MOTELstyle. -
A circle with a radius of 300 meters will be drawn around the center.
3.1.4 Map Request with Center, Base Map, Dynamically Defined Theme, and Other Features
Example 3-4 requests a map with a specified center, a predefined theme named theme_lbs_customers, a dynamically defined theme named sales_by_region, and all base themes in the base map us_base_road, plus two features: a polygon representing the top sales region, and a point. The requested map will be stored at the MapViewer host and a URL to that GIF image (format="GIF_URL") will be returned to the requester.
Example 3-4 Map Request with Center, Base Map, Dynamically Defined Theme, Other Features
<?xml version="1.0" encoding="UTF-8" ?>
<map_request datasource="lbs_data2" title="LBS CUSTOMER MAP 2"
width="400" height="300" format="GIF_URL" basemap="us_base_road">
<center size="1.5">
<geoFeature typeName="nil">
<geometricProperty>
<Point>
<coordinates>-122.2615, 37.5266</coordinates>
</Point>
</geometricProperty>
</geoFeature>
</center>
<themes>
<theme name="theme_lbs_customers"/>
<theme name="sales_by_region">
<jdbc_query spatial_column ="region"
label_column="manager"
render_style="V.SALES COLOR"
label_style="T.SMALL TEXT"
jdbc_host="data.my_corp.com"
jdbc_sid="orcl"
jdbc_port="1521"
jdbc_user="scott"
jdbc_password="password"
jdbc_mode="thin"
> select region, sales, manager from my_corp_sales_2001
</jdbc_query>
</theme>
</themes>
<geoFeature typeName="nil" label="TopSalesRegion"
text_style="9988" render_style="2837">
<geometricProperty>
<Polygon srsName="SDO:8265">
<outerBoundaryIs>
<LinearRing>
<coordinates>42.9,71.1 43.2,72.3 39.2,73.0 39.0,
73.1 42.9,71.1</coordinates>
</LinearRing>
</outerBoundaryIs>
</Polygon>
</geometricProperty>
</geoFeature>
<geoFeature render_style="1397" text_style="9987">
<geometricProperty>
<Point>
<coordinates>-122.5615, 37.3266</coordinates>
</Point>
</geometricProperty>
</geoFeature>
</map_request>
In Example 3-4, sales_by_region is a dynamically defined theme. For information about dynamically defining a theme, see Section 3.2.20 and Section 3.2.9.
3.1.5 Map Request for Point Features with Attribute Value and Dynamically Defined Variable Marker Style
Example 3-5 shows a map request to render point features with a dynamically defined variable marker style. The attribute_values attribute defines the value that will be used to find the appropriate bucket (for the range into which the value falls), as defined in the variable marker style.
Example 3-5 Map Request for Point Features with Attribute Value and Dynamically Defined Variable Marker Style
<?xml version="1.0" standalone="yes"?>
<map_request
title="Point Features with Variable Marker Style"
datasource="mvdemo"
srid="0"
width="500"
height="375"
bgcolor="#a6caf0"
antialiase="true"
format="PNG_URL">
<center size="19.2">
<geoFeature>
<geometricProperty typeName="center">
<Point>
<coordinates>-116.65,38.92</coordinates>
</Point>
</geometricProperty>
</geoFeature>
</center>
<geoFeature
render_style="varmarkerpf"
attribute_values="50000.0">
<geometricProperty>
<Point>
<coordinates>-112.0,43.0</coordinates>
</Point>
</geometricProperty>
</geoFeature>
<geoFeature
render_style="varmarkerpf"
attribute_values="125000.0">
<geometricProperty>
<Point>
<coordinates>-123.0,40.0</coordinates>
</Point>
</geometricProperty>
</geoFeature>
<geoFeature
render_style="varmarkerpf"
attribute_values="200000.0">
<geometricProperty>
<Point>
<coordinates>-116.64,38.92</coordinates>
</Point>
</geometricProperty>
</geoFeature>
<geoFeature
render_style="varmarkerpf"
attribute_values="300000.0">
<geometricProperty>
<Point>
<coordinates>-112.0,35.0</coordinates>
</Point>
</geometricProperty>
</geoFeature>
<styles>
<style name="varmarkerpf">
<AdvancedStyle>
<VariableMarkerStyle basemarker="mkcircle" startsize="10"
increment="5">
<Buckets>
<RangedBucket label="less than 100k" high="100000.0"/>
<RangedBucket label="100k - 150k" low="100000.0" high="150000.0"/>
<RangedBucket label="150k - 250k" low="150000.0" high="250000.0"/>
<RangedBucket label="250k - 350k" low="250000.0" high="350000.0"/>
</Buckets>
</VariableMarkerStyle>
</AdvancedStyle>
</style>
<style name="mkcircle">
<svg>
<g class="marker" style="stroke:blue;fill:red;">
<circle r="20"/>
</g>
</svg>
</style>
</styles>
</map_request>
3.1.6 Map Request with an Image Theme
Example 3-6 requests a map in which an image theme is to be plotted underneath all other regular vector data. The image theme is specified in the <jdbc_image_query> element as part of the <theme> element in a map request. (For an explanation of image themes, see Section 2.3.3.)
Example 3-6 Map Request with an Image Theme
<?xml version="1.0" encoding="UTF-8" ?>
<map_request datasource="lbs_data" title="LBS Image MAP"
basemap="us_roads" format="GIF_STREAM">
<center size="1">
<geoFeature>
<geometricProperty>
<Point>
<coordinates>-122.2615, 37.5266</coordinates>
</Point>
</geometricProperty>
</geoFeature>
</center>
<themes>
<theme name="anImageTheme">
<jdbc_image_query image_format="ECW"
image_column="image"
image_mbr_column="img_extent"
jdbc_srid="33709"
datasource="lbs_data">
SELECT image, img_extent, image_id FROM my_images
</jdbc_image_query>
</theme>
</themes>
</map_request>
MapViewer processes the request in Example 3-6 as follows:
-
MapViewer retrieves the image data by executing the user-supplied query (
SELECT image, img_extent, image_id FROM my_images) in the current map window context. -
MapViewer checks its internal list of all registered image renderers to see if one supports the ECW format (
image_format="ECW"). Because MapViewer as supplied by Oracle does not support the ECW format, you must implement and register a custom image renderer that supports the format, as explained in Appendix C. -
MapViewer calls the
renderImagesmethod, and image data retrieved from the user-supplied query is passed to the method as one of its parameters. -
MapViewer retrieves and renders any requested vector data on top of the rendered image.
3.1.7 Map Request for Image of Map Legend Only
Example 3-7 requests a map with just the image of the map legend, but without rendering any spatial data. In this example, the legend explains the symbology used for identifying cities, state boundaries, interstate highways, and county population density. (Map legends are explained in Section 3.2.11.)
Example 3-7 Map Request for Image of Map Legend Only
<?xml version="1.0" standalone="yes"?>
<map_request
datasource = "mvdemo"
format="PNG_URL">
<legend bgstyle="fill:#ffffff;stroke:#ff0000" profile="MEDIUM" position="SOUTH_EAST">
<column>
<entry text="Map Legend" is_title="true"/>
<entry style="M.STAR" text="center point"/>
<entry style="M.CITY HALL 3" text="cities"/>
<entry is_separator="true"/>
<entry style="C.ROSY BROWN STROKE" text="state boundary"/>
<entry style="L.PH" text="interstate highway"/>
<entry text="County population:"/>
<entry style="V.COUNTY_POP_DENSITY" tab="1"/>
</column>
</legend>
</map_request>
Generating just the map legend image, as in Example 3-7, can save processing time if you display the stored map legend image on a Web page separately from the actual displayed maps. This avoids the need to generate a legend each time there is a map request.
3.1.8 Map Request with SRID Different from Data SRID
Example 3-8 requests a map displayed in a coordinate system (srid="32775" for US - Equal Area Projection) that is different from the coordinate system associated with the county theme data (jdbc_srid="8265" for Longitude/Latitude - NAD 83). As a result, during the rendering process, MapViewer converts all geometries from the data SRID to the map request SRID.
If no coordinate system is associated with the theme data, MapViewer assumes that the data is associated with the coordinate system of the map request, and no conversion occurs.
Example 3-8 Map Request with SRID Different from Data SRID
<?xml version="1.0" standalone="yes"?>
<map_request
title="US Counties: Equal-Area Projection (SRID=32775)"
datasource="mvdemo"
srid="32775"
width="500"
height="375"
bgcolor="#a6caf0"
antialiase="true"
format="PNG_URL">
<center size="4000000.0">
<geoFeature>
<geometricProperty typeName="center">
<Point>
<coordinates>-218191.9643,1830357.1429</coordinates>
</Point>
</geometricProperty>
</geoFeature>
</center>
<themes>
<theme name="county_th" user_clickable="false">
<jdbc_query
spatial_column="geom"
render_style="C.COUNTIES"
jdbc_srid="8265"
datasource="mvdemo"
asis="false">select geom from counties</jdbc_query>
</theme>
</themes>
</map_request>
3.1.9 Map Request Using a Pie Chart Theme
This section shows how to use thematic mapping with a pie chart theme. The result is a map in which each county contains a pie chart in which the size of each slice reflects the proportion of the population in a specified household income level category (low, medium, or high) in the county.
The basic steps are as follows.
-
Create an advanced style that defines the characteristics of the pie charts to be used. The following example creates an advanced style named
V.PIECHART1.INSERT INTO user_sdo_styles VALUES ( 'V.PIECHART1', 'ADVANCED', null, '<?xml version="1.0" ?> <AdvancedStyle> <PieChartStyle pieradius="10"> <PieSlice name="low" color="#ff0000"/> <PieSlice name="medium" color="#ffff00"/> <PieSlice name="high" color="#00ff00"/> </PieChartStyle> </AdvancedStyle>', null, null);When the style defined in the preceding example is applied to a geographic feature, a pie chart is created with three slices. The
pieradiusattribute specifies the size of each pie chart in pixels. Each slice (<PieSlice>element) has a color defined for it. Thenameattribute for each slice is ignored by MapViewer. -
Create a new theme that uses the style that you created, as in the following example:
INSERT INTO user_sdo_themes VALUES ( 'THEME_PIE_CHART', null, 'COUNTIES', 'GEOM', '<?xml version="1.0" standalone="yes"?> <styling_rules> <rule column="INC_LOW,INC_MED,INC_HIGH"> <features style="C.US MAP YELLOW"> </features> <label column="''dummy''" style="V.PIECHART1"> 1 </label> </rule> </styling_rules>');In the theme definition in the preceding example, the
<label>element of the styling rule specifiesstyle="V.PIECHART1", to indicate that this pie chart style (the style created in Step 1) is used to label each geometry displayed on the map.The column attribute (
column="''dummy''"in this example) is required, even though it has no effect on the resulting map. Thecolumnattribute value can bedummyor any other string, and the value must be enclosed on both sides by two single quotation marks.Because the
V.PIECHART1style is defined with three slices, the preceding example must specify the names of three columns from the COUNTIES table, and these columns must have a numeric data type. The column names are INC_LOW, INC_MED, and INC_HIGH. These columns will supply the value that will be used to determine the size of each pie slice. -
Issue a map request that uses the theme that you created. Example 3-9 requests a map that uses the
THEME_PIE_CHARTtheme that was created in Step 2.
Example 3-9 Map Request Using a Pie Chart Theme
<?xml version="1.0" standalone="yes"?>
<map_request datasource = "mvdemo"
format="PNG_STREAM">
<themes>
<theme name="THEME_PIE_CHART"/>
</themes>
</map_request>
Figure 3-1 shows part of a display resulting from the map request in Example 3-9.
Figure 3-1 Map Display Using a Pie Chart Theme
Description of "Figure 3-1 Map Display Using a Pie Chart Theme"
You can also use the pie chart style in a dynamic (JDBC) theme when issuing a map request. You must specify the complete SQL query for a JDBC theme in the map request, because you must identify the attribute columns that are needed by the pie chart style. Any columns in the SELECT list that are not SDO_GEOMETRY columns or label columns are considered to be attribute columns that can be used by an advanced style.
Example 3-10 is a sample request with a JDBC theme using a pie chart style. The SQL query (SELECT geom, 'dummy', sales, service, training FROM support_centers) is included in the theme definition.
Example 3-10 JDBC Theme Using a Pie Chart Style
<?xml version="1.0" standalone="yes"?>
<map_request
basemap="CA_MAP"
datasource = "mvdemo"
format="PNG_URL">
<themes>
<theme name="support_center">
<jdbc_query spatial_column="geom" datasource="tilsmenv"
label_column="dummy",
label_style="V.PIECHART1">
SELECT geom, 'dummy', sales, service, training
FROM support_centers
</jdbc_query>
</theme>
</themes>
</map_request>
3.1.10 Map Request Using Ratio Scale and Mixed Theme Scale Modes
Example 3-11 requests a map specifying a center and a ratio scale to define the map area. Two themes are used: a predefined theme named THEME_US_COUNTIES1, which uses the default screen inch scale mode, and a JDBC theme names STATES_TH, which uses the ratio mode.
Example 3-11 Map Request Using Ratio Scale and Mixed Theme Scale Modes
<?xml version="1.0" standalone="yes"?> <map_request title="States (ratio), counties (screen inch), center and scale" datasource="tilsmenv" width="500" height="400" bgcolor="#a6caf0" antialiase="true" format="PNG_URL" > <center scale="5000000"> <geoFeature> <geometricProperty typeName="center"> <Point> <coordinates>-90.0,32.0</coordinates> </Point> </geometricProperty> </geoFeature> </center> <themes> <theme name="STATES_TH" min_scale="5.0E7" max_scale="1.0E7" scale_mode="ratio"> <jdbc_query label_column="STATE" spatial_column="geom" label_style="T.STATE NAME" render_style="C.COUNTIES" jdbc_srid="8265" datasource="tilsmenv" asis="false">select geom,state from states </jdbc_query> </theme> <theme name="THEME_US_COUNTIES1" min_scale="2.286" /> </themes> </map_request>
3.1.11 Map Request Using Predefined Theme (Binding Parameter and Custom Type)
Example 3-12 requests a map using a predefined theme with a styling rule that selects all counties where a state abbreviation is in the selection list. When the predefined theme is created, the selection list is represented as a binding parameter, as follows:
INSERT INTO user_sdo_themes VALUES (
'COUNTIES_BY_STATES', null, 'COUNTIES', 'GEOM',
'<styling_rules>
<rule>
<features style="C.COUNTIES"> (state_abrv in (select column_value from table(:1))) </features>
<label column="COUNTY" style="T.CITY NAME"> 1 </label>
</rule>
</styling_rules>');
This binding parameter can accept one or more values, for which you can create a custom SQL data type that represents this set of values, as follows:
CREATE OR REPLACE TYPE string_array AS TABLE OF VARCHAR2(64);
Then, you can use this custom data type on the binding parameter of the map request, as shown in Example 3-12.
Example 3-12 Map Request Using Predefined Theme (Binding Parameter and Custom Type)
<?xml version="1.0" standalone="yes"?>
<map_request
title="Binding Parameters and STRING_ARRAY type"
datasource = "mvdemo"
width="640"
height="480"
bgcolor="#a6cae0"
antialiase="false"
format="PNG_STREAM">
<themes>
<theme name="COUNTIES_BY_STATES" >
<binding_parameters>
<parameter value="FL,ME,CA,OH" type="STRING_ARRAY"/>
</binding_parameters>
</theme>
</themes>
</map_request>
3.1.12 Map Request Using Advanced Styles and Rendering Rules
Example 3-13 requests a map using the <rendering> element, and it combines two advanced styles that are based on different columns. In this example, an advanced style named POPVMK is based on column POP90, and another advanced style named EQRBRANK is based on column RANK90. Point features (from the CITIES table) are rendered. The shape of the feature is defined by the advanced style associated with column POP90, and the feature color is defined by the advanced style associated with column RANK90.
Example 3-13 Map Request Using Advanced Styles and Rendering Rules
<?xml version="1.0" standalone="yes"?>
<map_request
title="Cross advanced styles"
datasource="mvdemo"
width="640"
height="480"
bgcolor="#a6caf0"
antialiase="false"
format="PNG_STREAM"
>
<center size="7.7">
<geoFeature>
<geometricProperty typeName="center">
<Point>
<coordinates>-72.96,41.25</coordinates>
</Point>
</geometricProperty>
</geoFeature>
</center>
<themes>
<theme name="cities">
<jdbc_query
label_column="city"
spatial_column="location"
label_style="T.CITY NAME"
jdbc_srid="8265"
datasource="mvdemo"
asis="false">select location,city,pop90,rank90 from cities
</jdbc_query>
<rendering>
<style name="POPVMK" value_columns="POP90">
<substyle name="EQRBRANK" value_columns="RANK90" changes="FILL_COLOR"/>
</style>
</rendering>
</theme>
</themes>
<styles>
<style name="STAR_TRANSP">
<svg width="1in" height="1in">
<desc/>
<g class="marker" style="stroke:#000000;fill:#FF0000;fill-opacity:0;width:15;height:15;font-family:Dialog;font-size:12;font-fill:#FF0000">
<polyline points="138.0,123.0,161.0,198.0,100.0,152.0,38.0,198.0,61.0,123.0,0.0,76.0,76.0,76.0,100.0,0.0,123.0,76.0,199.0,76.0"/>
</g>
</svg>
</style>
<style name="POPVMK">
<AdvancedStyle>
<VariableMarkerStyle basemarker="STAR_TRANSP" startsize="7" increment="5">
<Buckets>
<RangedBucket seq="0" label="100217 - 1905803.75" low="100217" high="1905803.75"/>
<RangedBucket seq="1" label="1905803.75 - 3711390.5" low="1905803.75" high="3711390.5"/>
<RangedBucket seq="2" label="3711390.5 - 5516977.25" low="3711390.5" high="5516977.25"/>
<RangedBucket seq="3" label="5516977.25 - 7322564" low="5516977.25" high="7322565"/>
</Buckets>
</VariableMarkerStyle>
</AdvancedStyle>
</style>
<style name="EQRBRANK">
<AdvancedStyle>
<BucketStyle>
<Buckets low="1" high="196" nbuckets="4" styles="C.RED,C.RB13_1,C.RB13_6,C.SEQ6_01"/>
</BucketStyle>
</AdvancedStyle>
</style>
</styles>
<legend bgstyle="fill:#ffffff;fill-opacity:50;stroke:#ff0000" profile="SMALL" position="SOUTH_EAST">
<column>
<entry text="Map Legend" is_title="true" />
<entry text="POP90:" />
<entry style="POPVMK" tab="1" />
<entry text="RANK90:" />
<entry style="EQRBRANK" tab="1" />
</column>
</legend>
</map_request>
3.1.13 Map Request Using Stacked Styles
Example 3-14 requests a map using the <rendering> element, and it defines multiple styles (C.COUNTIES and PIECHART1) to be applied on each theme feature.
Example 3-14 Map Request Using Stacked Styles
<?xml version="1.0" standalone="yes"?>
<map_request
title="Theme with Stacked Styles"
datasource="mvdemo"
width="600"
height="450"
bgcolor="#a6caf0"
antialiase="true"
format="PNG_STREAM"
>
<center size="18">
<geoFeature>
<geometricProperty typeName="center">
<Point>
<coordinates>-122.729,40.423</coordinates>
</Point>
</geometricProperty>
</geoFeature>
</center>
<themes>
<theme name="STACKEDSTYLES">
<jdbc_query
label_column="state"
spatial_column="geom"
label_style="T.STATE NAME"
jdbc_srid="8265"
datasource="mvdemo"
asis="false">select geom,state,HHI0_10,HHI10_15,HHI100UP,HHI15_25,HHI25_35 from states
</jdbc_query>
<rendering>
<style name="C.COUNTIES"/>
<style name="PIECHART1" value_columns="HHI0_10,HHI10_15,HHI100UP,HHI15_25,HHI25_35"/>
</rendering>
</theme>
</themes>
<styles>
<style name="piechart1">
<AdvancedStyle>
<PieChartStyle pieradius="10">
<PieSlice name="A" color="#FFFF00"/>
<PieSlice name="B" color="#000000"/>
<PieSlice name="H" color="#FF00FF"/>
<PieSlice name="I" color="#0000FF"/>
<PieSlice name="W" color="#FFFFFF"/>
</PieChartStyle>
</AdvancedStyle>
</style>
</styles>
</map_request>
3.1.14 WFS Map Requests
This section contains examples of WFS map requests, one using a predefined theme and one using a dynamic theme.
Example 3-15 requests a map using a predefined WFS theme named BC_MUNICIPALITY, which is defined as follows:
INSERT INTO user_sdo_themes VALUES ( 'BC_MUNICIPALITY', 'WFS theme', 'BC_MUNICIPALITY', 'THE_GEOM', '<?xml version="1.0" standalone="yes"?> <styling_rules theme_type="wfs" service_url="http://www.refractions.net:8080/geoserver/wfs/GetCapabilities?" srs="EPSG:3005"> <rule> <features style="C.BLUE"> </features> <label column="name" style="T.CITY NAME"> 1 </label> </rule> </styling_rules>');
Example 3-15 shows a map request that renders this predefined WFS theme.
Example 3-15 Map Request Using Predefined WFS Theme
<?xml version="1.0" standalone="yes"?>
<map_request
title="Predefined WFS MAP"
datasource = "mvdemo"
width="640"
height="480"
bgcolor="#a6cae0"
antialiase="true"
format="PNG_STREAM">
<center size="76000">
<geoFeature>
<geometricProperty typeName="center">
<Point>
<coordinates>1260500,470000</coordinates>
</Point>
</geometricProperty>
</geoFeature>
</center>
<themes>
<theme name="bc_municipality" />
</themes>
</map_request>
Example 3-16 shows a map request that uses a dynamic WFS theme.
Example 3-16 Map Request Using Dynamic WFS Theme
<?xml version="1.0" standalone="yes"?>
<map_request
title="WFS MAP"
datasource = "mvdemo"
width="640"
height="480"
bgcolor="#a6cae0"
antialiase="true"
format="PNG_STREAM">
<center size="76000">
<geoFeature>
<geometricProperty typeName="center">
<Point>
<coordinates>1260500,470000</coordinates>
</Point>
</geometricProperty>
</geoFeature>
</center>
<themes>
<theme name="wfs" >
<wfs_feature_request
service_url="http://www.refractions.net:8080/geoserver/wfs/GetCapabilities?"
srs="EPSG:3005"
feature_name="bc_hospitals"
spatial_column="the_geom"
render_style="M.STAR"
label_column="name"
label_style="T.CITY NAME"
datasource="mvdemo" />
</theme>
</themes>
</map_request>
Example 3-17 shows a map request for a dynamic WFS theme with an advanced style to render features.
Example 3-17 Map Request Using Dynamic WFS Theme with an Advanced Style
<?xml version="1.0" standalone="yes"?>
<map_request
title="WFS Theme with Advanced Style"
datasource = "mvdemo"
width="640"
height="480"
bgcolor="#a6cae0"
antialiase="true"
format="PNG_STREAM">
<center size="10.">
<geoFeature >
<geometricProperty typeName="center">
<Point>
<coordinates>-70., 44.</coordinates>
</Point>
</geometricProperty>
</geoFeature>
</center>
<themes>
<theme name="wfs" >
<wfs_feature_request
service_url="http://199.29.1.81:8181/miwfs/GetFeature.ashx?"
srs="EPSG:4326"
feature_name="usa"
spatial_column="obj"
render_style="CBSTATES"
label_column="STATE_NAME"
label_style="T.CITY NAME"
feature_attributes="state"
datasource="mvdemo" />
</theme>
</themes>
<styles>
<style name="CBSTATES">
<AdvancedStyle>
<BucketStyle>
<Buckets default_style="C.COUNTIES">
<CollectionBucket seq="0" type="string" style="C.RB13_13">MA</CollectionBucket>
<CollectionBucket seq="1" type="string" style="C.RB13_1">NH</CollectionBucket>
<CollectionBucket seq="2" type="string" style="C.RB13_7">ME</CollectionBucket>
</Buckets>
</BucketStyle>
</AdvancedStyle>
</style>
</styles>
</map_request>
3.1.15 Java Program Using MapViewer
Example 3-18 uses the java.net package to send an XML request to MapViewer and to receive the response from MapViewer. (Note, however, most programmers will find it more convenient to use the JavaBean-based API, described in Chapter 4, or the JSP tag library, described in Chapter 5.)
Example 3-18 Java Program That Interacts with MapViewer
import java.net.*;
import java.io.*;
/**
* A sample program that shows how to interact with MapViewer
*/
public class MapViewerDemo
{
private HttpURLConnection mapViewer = null;
/**
* Initializes this demo with the URL to the MapViewer server.
* The URL is typically http://my_corp.com:8888/mapviewer/omserver.
*/
public MapViewerDemo(String mapViewerURLString)
{
URL url;
try
{
url = new URL(mapViewerURLString);
mapViewer = (HttpURLConnection) url.openConnection();
mapViewer.setDoOutput(true);
mapViewer.setDoInput(true);
mapViewer.setUseCaches(false);
}
catch (Exception e)
{
e.printStackTrace(System.err);
System.exit(1);
}
}
/**
* Submits an XML request to MapViewer.
* @param xmlreq the XML document that is a MapViewer request
*/
public void submitRequest(String xmlreq)
{
try
{
mapViewer.setRequestMethod("POST"); //Use HTTP POST method.
OutputStream os = mapViewer.getOutputStream();
//MapViewer expects to find the request as a parameter
//named "xml_request".
xmlreq = "xml_request="+URLEncoder.encode(xmlreq);
os.write(xmlreq.getBytes());
os.flush();
os.close();
}
catch (Exception e)
{
e.printStackTrace(System.err);
System.exit(1);
}
}
/**
* Receives an XML response from MapViewer.
*/
public String getResponse()
{
ByteArrayOutputStream content = new ByteArrayOutputStream();
InputStream is = null;
try
{
is = mapViewer.getInputStream();
int c;
while ((c = is.read()) != -1)
content.write(c);
is.close();
content.flush();
content.close();
return content.toString();
}
catch (Exception e)
{
e.printStackTrace(System.err);
return null;
}
}
// A simple main program that sends a list_data_sources XML
// request to MapViewer through HTTP POST
public static void main(String[] args)
{
if(args.length<1)
{
System.out.println("Usage: java MapViewerDemo <mapviewer url>");
System.out.println("Example: java MapViewerDemo http://my_corp.com/mapviewer/omserver");
System.exit(1);
}
// A sample XML request for MapViewer
String
listDataSources = "<?xml version=\"1.0\" standalone=\"yes\"?>" +
" <non_map_request>" +
" <list_data_sources/>" +
" </non_map_request>";
MapViewerDemo tester = null;
tester = new MapViewerDemo(args[0]);
System.out.println("submitting request:\n"+listDataSources);
tester.submitRequest(listDataSources);
String response = tester.getResponse();
System.out.println("response from MapViewer: \n" + response);
}
}
3.1.16 PL/SQL Program Using MapViewer
Example 3-19 is a sample PL/SQL program that sends an XML request to the MapViewer server.
Example 3-19 PL/SQL Program That Interacts with MapViewer
set serverout on size 1000000;
--
-- Author: Clarke Colombo
--
declare
l_http_req utl_http.req;
l_http_resp utl_http.resp;
l_url varchar2(4000):= 'http://my_corp.com:8888/mapviewer/omserver';
l_value varchar2(4000);
img_url varchar2(4000);
response sys.xmltype;
output varchar2(255);
map_req varchar2(4000);
begin
utl_http.set_persistent_conn_support(TRUE);
map_req := '<?xml version="1.0" standalone="yes"?>
<map_request title="MapViewer Demonstration"
datasource="mvdemo"
basemap="course_map"
width="500"
height="375"
bgcolor="#a6cae0"
antialiasing="false"
format="GIF_URL">
<center size="5">
<geoFeature>
<geometricProperty>
<Point>
<coordinates>-122.2615, 37.5266</coordinates>
</Point>
</geometricProperty>
</geoFeature>
</center>
</map_request>';
l_http_req := utl_http.begin_request(l_url, 'POST', 'HTTP/1.0');
--
-- Sets up proper HTTP headers.
--
utl_http.set_header(l_http_req, 'Content-Type', 'application/x-www-form-urlencoded');
utl_http.set_header(l_http_req, 'Content-Length', length('xml_request=' || map_req));
utl_http.set_header(l_http_req, 'Host', 'my_corp.com');
utl_http.set_header(l_http_req, 'Port', '8888');
utl_http.write_text(l_http_req, 'xml_request=' || map_req);
--
l_http_resp := utl_http.get_response(l_http_req);
utl_http.read_text(l_http_resp, l_value);
response := sys.xmltype.createxml (l_value);
utl_http.end_response(l_http_resp);
img_url := response.extract('/map_response/map_image/map_content/@url').getstringval();
dbms_output.put_line(img_url);
end;
/
3.2 Map Request DTD
The following is the complete DTD for a map request, which is followed by reference sections that describe each element and its attributes.
<?xml version="1.0" encoding="UTF-8"?>
<!-- <box> is defined in OGC GML v1.0 -->
<!ELEMENT map_request ((box | center | bounding_themes)?, srs?, legend?, themes?,
styles?, scale_bar?, north_arrow?, geoFeature*)>
<!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
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
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*
>
<!ELEMENT center (geoFeature)>
<!ATTLIST center
size CDATA #REQUIRED
>
<!ELEMENT box (coordinates) >
<!ATTLIST box
ID CDATA #IMPLIED
srsName CDATA #REQUIRED
preserve_aspect_ratio (TRUE|FALSE) "FALSE"
>
<!ELEMENT bounding_themes (#PCDATA) >
<!ATTLIST bounding_themes
border_margin CDATA #IMPLIED
preserve_aspect_ratio CDATA "TRUE"
size_hint CDATA #IMPLIED
>
<!ELEMENT srs (#PCDATA) >
<!ELEMENT themes (theme+) >
<!ELEMENT theme (jdbc_query | jdbc_image_query | jdbc_georaster_query
| jdbc_network_query | jdbc_topology_query
| map_tile_theme
)? >
<!ATTLIST theme
name CDATA #REQUIRED
datasource CDATA #IMPLIED
max_scale CDATA #IMPLIED
min_scale CDATA #IMPLIED
label_always_on (TRUE|FALSE) "FALSE"
fast_unpickle (TRUE|FALSE) "TRUE"
mode CDATA #IMPLIED
min_dist CDATA #IMPLIED
fixed_svglabel (TRUE|FALSE) "FALSE"
visible_in_svg (TRUE|FALSE) "TRUE"
selectable_in_svg (TRUE|FALSE) "FALSE"
part_of_basemap (TRUE|FALSE) "FALSE"
simplify_shapes (TRUE|FALSE) "TRUE"
onclick CDATA #IMPLIED
onmousemove CDATA #IMPLIED
onmouseover CDATA #IMPLIED
onmouseout CDATA #IMPLIED
workspace_name CDATA #IMPLIED
workspace_savepoint CDATA #IMPLIED
workspace_date CDATA #IMPLIED
workspace_date_format CDATA #IMPLIED
>
<!ELEMENT jdbc_query (#PCDATA, hidden_info?)>
<!ATTLIST jdbc_query
asis (TRUE|FALSE) "FALSE"
spatial_column CDATA #REQUIRED
key_column CDATA #IMPLIED
label_column CDATA #IMPLIED
label_style CDATA #IMPLIED
render_style CDATA #IMPLIED
datasource CDATA #IMPLIED
jdbc_host CDATA #IMPLIED
jdbc_port CDATA #IMPLIED
jdbc_sid CDATA #IMPLIED
jdbc_user CDATA #IMPLIED
jdbc_password CDATA #IMPLIED
jdbc_srid CDATA #IMPLIED
jdbc_mode (thin|oci8) "thin"
>
<!ELEMENT hidden_info (field+)>
<!ELEMENT field (#PCDATA)>
<!ATTLIST field
column CDATA #REQUIRED
name CDATA #IMPLIED
>
<!ELEMENT jdbc_image_query (#PCDATA) >
<!ATTLIST jdbc_image_query
asis (TRUE|FALSE) "FALSE"
image_format CDATA #REQUIRED
image_column CDATA #REQUIRED
image_mbr_column CDATA #REQUIRED
image_resolution CDATA #IMPLIED
image_unit CDATA #IMPLIED
datasource CDATA #IMPLIED
jdbc_host CDATA #IMPLIED
jdbc_port CDATA #IMPLIED
jdbc_sid CDATA #IMPLIED
jdbc_user CDATA #IMPLIED
jdbc_password CDATA #IMPLIED
jdbc_srid CDATA #IMPLIED
jdbc_mode (thin|oci8) "thin"
>
<!ELEMENT jdbc_georaster_query (#PCDATA) >
<!ATTLIST jdbc_georaster_query
asis (TRUE|FALSE) "FALSE"
georaster_table CDATA #REQUIRED
georaster_column CDATA #REQUIRED
raster_id CDATA #IMPLIED
raster_table CDATA #IMPLIED
raster_pyramid CDATA #IMPLIED
raster_bands CDATA #IMPLIED
datasource CDATA #IMPLIED
polygon_mask CDATA #IMPLIED
transparent_nodata CDATA #IMPLIED
jdbc_host CDATA #IMPLIED
jdbc_port CDATA #IMPLIED
jdbc_sid CDATA #IMPLIED
jdbc_user CDATA #IMPLIED
jdbc_password CDATA #IMPLIED
jdbc_srid CDATA #IMPLIED
jdbc_mode (thin|oci8) "thin">
<!ELEMENT jdbc_network_query (#PCDATA) >
<!ATTLIST jdbc_network_query
asis (TRUE|FALSE) "FALSE"
network_name CDATA #REQUIRED
network_level CDATA #IMPLIED
link_style CDATA #IMPLIED
direction_style CDATA #IMPLIED
direction_position CDATA #IMPLIED
direction_markersize CDATA #IMPLIED
link_labelstyle CDATA #IMPLIED
link_labelcolumn CDATA #IMPLIED
node_style CDATA #IMPLIED
node_markersize CDATA #IMPLIED
node_labelstyle CDATA #IMPLIED
node_labelcolumn CDATA #IMPLIED
path_ids CDATA #IMPLIED
path_styles CDATA #IMPLIED
path_labelstyle CDATA #IMPLIED
path_labelcolumn CDATA #IMPLIED
analysis_algorithm CDATA #IMPLIED
shortestpath_style CDATA #IMPLIED
shortestpath_startnode CDATA #IMPLIED
shortestpath_endnode CDATA #IMPLIED
shortestpath_startstyle CDATA #IMPLIED
shortestpath_endstyle CDATA #IMPLIED
withincost_startnode CDATA #IMPLIED
withincost_style CDATA #IMPLIED
withincost_cost CDATA #IMPLIED
withincost_startstyle CDATA #IMPLIED
datasource CDATA #IMPLIED
jdbc_host CDATA #IMPLIED
jdbc_port CDATA #IMPLIED
jdbc_sid CDATA #IMPLIED
jdbc_user CDATA #IMPLIED
jdbc_password CDATA #IMPLIED
jdbc_srid CDATA #IMPLIED
jdbc_mode (thin|oci8) "thin"
>
<!ELEMENT jdbc_topology_query (#PCDATA)>
<!ATTLIST jdbc_topology_query
asis (TRUE|FALSE) "FALSE"
topology_name CDATA #REQUIRED
feature_table CDATA #REQUIRED
spatial_column CDATA #REQUIRED
label_column CDATA #IMPLIED
label_style CDATA #IMPLIED
render_style CDATA #IMPLIED
datasource CDATA #IMPLIED
edge_style CDATA #IMPLIED
edge_marker_style CDATA #IMPLIED
edge_marker_size CDATA #IMPLIED
edge_label_style CDATA #IMPLIED
node_style CDATA #IMPLIED
node_label_style CDATA #IMPLIED
face_style CDATA #IMPLIED
face_label_style CDATA #IMPLIED
jdbc_host CDATA #IMPLIED
jdbc_port CDATA #IMPLIED
jdbc_sid CDATA #IMPLIED
jdbc_user CDATA #IMPLIED
jdbc_password CDATA #IMPLIED
jdbc_srid CDATA #IMPLIED
jdbc_mode (thin|oci8) "thin"
>
<!ELEMENT map_tile_theme (#PCDATA)>
<!ATTLIST map_tile_theme
map_tile_layer CDATA # REQUIRED
snap_to_tile_scale (TRUE|FALSE) "FALSE"
>
<!ELEMENT geoFeature (description?, property*,
geometricProperty)>
<!ATTLIST geoFeature
typeName CDATA #IMPLIED
id CDATA #IMPLIED
render_style CDATA #IMPLIED
text_style CDATA #IMPLIED
label CDATA #IMPLIED
label_always_on (TRUE|FALSE) "FALSE"
marker_size CDATA #IMPLIED
radius CDATA #IMPLIED
attribute_values CDATA #IMPLIED
orient_x CDATA #IMPLIED
orient_y CDATA #IMPLIED
orient_z CDATA #IMPLIED
selectable_in_svg (TRUE|FALSE) "FALSE"
onclick CDATA #IMPLIED
hidden_info CDATA #IMPLIED
>
<!ELEMENT legend column+ >
<!ATTLIST legend
bgstyle CDATA #implied
font CDATA #implied
location_x CDATA #implied
location_y CDATA #implied
offset_x CDATA #implied
offset_y CDATA #implied
profile (MEDIUM|SMALL|LARGE) "MEDIUM"
position (SOUTH_WEST|SOUTH_EAST|SOUTH|NORTH|
NORTH_WEST|NORTH_EAST|EAST|WEST|CENTER) "SOUTH_WEST"
>
<!ELEMENT column entry+ >
<!ATTLIST entry
is_title (true|false) "false"
is_separator (true|false) "false"
tab CDATA "0"
style CDATA #implied
text CDATA #implied
>
<!ELEMENT scale_bar >
<!ATTLIST scale_bar
mode (METRIC_MODE|US_MODE|DUAL_MODES) "METRIC_MODE"
position (SOUTH_WEST|SOUTH_EAST|SOUTH|NORTH|
NORTH_WEST|NORTH_EAST) "NORTH_EAST"
offset_y CDATA #implied
offset_y CDATA #implied
color1 CDATA #implied
color1_opacity CDATA #implied
color2 CDATA #implied
color2_opacity CDATA #implied
length_hint CDATA #implied
label_color CDATA #implied
label_font_family CDATA #implied
label_font_size CDATA #implied
label_halo_size CDATA #implied
label_position (TOP|BOTTOM) "TOP"
>
<!ELEMENT styles (style+) >
<!ELEMENT style (svg | AdvancedStyle)?>
<!ATTLIST style
name CDATA #REQUIRED
>
<!ELEMENT north_arrow (style, location?, size?) >
The main elements and attributes of the map request DTD are explained in sections that follow. The <map_request> element is described in Section 3.2.1. The remaining related elements are described, in alphabetical order by element name, in the following sections:
3.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 Section 3.2.3), <center> (see Section 3.2.4), or <bounding_themes> (see Section 3.2.2), 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 Section 3.2.11) 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 Section 3.2.21) specifies predefined or dynamically defined themes.
The optional <styles> element (see Section 3.2.19) specifies dynamically defined styles.
The <geoFeature> element (see Section 3.2.5) can be used to specify any number of individual geometries and their rendering attributes.
The optional <north_arrow> element (see Section 3.2.13) 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.
3.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.1. 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 aMapResponseobject and returned to the client. If you specifyGIF_STREAM, the generated image map content is returned directly to the client through the HTTP MIME typeimage/gif. -
If you specify
JAVA_IMAGE, a Java 2DBufferedImageobject with a color model ofTYPE_INT_RGBis embedded in aMapResponseobject and returned to the client. -
If you specify
PNG_STREAM, the stream of the image in nonindexed PNG format is returned directly; if you specifyPNG_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 specifyPNG8_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 specifyJPEG_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 specifyPDF_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 specifySVG_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 specifySVGZ_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 specifySVGTINY_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 run time 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.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 8.2.
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.
3.2.2 bounding_themes Element
The <bounding_themes> element has the following definition:
<!ELEMENT bounding_themes (#PCDATA) >
<!ATTLIST bounding_themes
border_margin CDATA #IMPLIED
preserve_aspect_ratio CDATA "TRUE"
size_hint CDATA #IMPLIED
>
You can specify one or more themes as the bounding themes when you cannot predetermine the data size for a map. For example, you may have one dynamic theme that selects all data points that meet certain criteria, and you then want to plot those data points on a map that is just big enough to enclose all the selected data points. In such cases, you can use the <bounding_themes> element to specify the names of such dynamic themes. MapViewer first processes any themes that are specified in the <bounding_themes> element, generates a bounding box based on the resulting features of the bounding themes, and then prepares other themes according to the new bounding box.
The <bounding_themes> element is ignored if you specify the <box> or <center> element in the map request.
border_margin is an optional attribute that specifies the percentage to be added to each margin of the generated bounding box. For example, if you specify a value of 0.025, MapViewer adds 2.5% of the width to the left and right margins of the generated bounding box (resulting in a total 5% width expansion in the x-axis); similarly, 2.5% of the height is added to the top and bottom margins. The default value is 0.05, or 5% to be added to each margin.
preserve_aspect_ratio is an optional attribute that indicates whether or not the bounding box generated after processing the bounding themes should be further modified so that it has the same aspect ratio as the map image or device. The default is TRUE, which modifies the bounding box to preserve the aspect ratio, so as not to distort the resulting map image.
size_hint is an optional attribute that specifies the vertical span of the map in terms of the original data unit. For example, if the user's data is in decimal degrees, the size_hint attribute specifies the number of decimal degrees in latitude. If the user's data is projected with meter as its unit, MapViewer interprets size_hint in meters.
The size_hint attribute can be used to extend the boundary limit. This is useful when the bounding theme has just one point feature. For example, the bounding theme can be a point resulting from a geocoding query, and you want to place this point in the middle of the map and extend the boundary from that point.
The element itself contains a comma-delimited list of names of the bounding themes. The theme names must exactly match their names in the map request or the base map used in the map request. The following example shows a map request with two bounding themes, named theme1 and theme3, and with 2 percent (border_margin="0.02") added to all four margins of the minimum bounding box needed to hold features associated with the two themes:
<?xml version="1.0" standalone="yes"?>
<map_request
title="bounding themes"
datasource = "tilsmenv"
basemap="qa_map"
width="400"
height="400"
bgcolor="#a6cae0"
antialiase="false"
mapfilename="tilsmq202"
format="PNG_STREAM">
<bounding_themes border_margin="0.02">theme1, theme3</bounding_themes>
<themes>
<theme name="theme1" min_scale="5.0E7" max_scale="0.0">
<jdbc_query
datasource="tilsmenv"
jdbc_srid="8265"
spatial_column="geom" label_column="STATE"
render_style="myPattern" label_style="myText"
>SELECT geom, state from states where state_abrv='IL'</jdbc_query>
</theme>
<theme name="theme3" min_scale="5.0E7" max_scale="0.0">
<jdbc_query
datasource="tilsmenv"
jdbc_srid="8265"
spatial_column="geom" label_column="STATE"
render_style="myPattern" label_style="myText"
>SELECT geom,state from states where state_abrv='IN'</jdbc_query>
</theme>
</themes>
<styles>
<style name="myPattern">
<svg width="1in" height="1in">
<desc></desc>
<g class="area"
style="stroke:#0000cc;fill:#3300ff;fill-opacity:128;line-style:L.DPH">
</g>
</svg>
</style>
<style name="myText">
<svg width="1in" height="1in">
<g class="text" float-width="3.0"
style="font-style:bold;font-family:Serif;font-size:18pt;fill:#000000">
Hello World!
</g>
</svg>
</style>
</styles>
</map_request>
The preceding example displays a map in which the states of Illinois and Indiana are displayed according to the specifications in the two <theme> elements, both of which specify a rendering style named myPattern. In the myText style, the text "Hello World!" is displayed only when the style is being previewed in a style creation tool, such as the Map Builder tool. When the style is applied to a map, it is supplied with an actual text label that MapViewer obtains from a theme.
Figure 3-2 shows the display from the preceding example.
3.2.3 box Element
The <box> element has the following definition:
<!ELEMENT box (coordinates) >
<!ATTLIST box
ID CDATA #IMPLIED
srsName CDATA #REQUIRED
preserve_aspect_ratio (TRUE|FALSE) "FALSE"
>
The <box> element is used to specify the bounding box of a resulting map. It uses a <coordinates> element to specify two coordinate value pairs that identify the lower-left and upper-right corners of the rectangle. The coordinate values are interpreted in terms of the user's data. For example, if the user's data is geodetic and is specified in decimal degrees of longitude and latitude, a <coordinates> specification of -72.84, 41.67, -70.88, 42.70 indicates a bounding box with the lower-left corner at longitude-latitude coordinates (-72.84, 41.67) and the upper-right corner at coordinates (-70.88, 42.70), which are in the New England region of the United States. However, if the data is projected with meter as its unit of measurement, the coordinate values are interpreted in meters.
preserve_aspect_ratio is an optional attribute that indicates whether or not the box coordinates should be further modified so that it has the same aspect ratio as the map image or device. The default is FALSE, in order to keep compatibility with previous versions that do not have this attribute. If this value is set to TRUE, the box is modified to preserve the aspect ratio, so as not to distort the resulting map image.
3.2.4 center Element
The <center> element has the following definition:
<!ELEMENT center (geoFeature)> <!ATTLIST center size CDATA #REQUIRED >
The <center> element is used to specify the center of a resulting map. It has a required attribute named size, which specifies the vertical span of the map in terms of the original data unit. For example, if the user's data is in decimal degrees, the size attribute specifies the number of decimal degrees in latitude. If the user's data is projected with meter as its unit, MapViewer interprets the size in meters.
The center itself must embed a <geoFeature> element, which is specified in Section 3.2.5.
3.2.5 geoFeature Element
The <geoFeature> element has the following definition:
<!ELEMENT geoFeature (description?, property*, geometricProperty)> <!ATTLIST geoFeature typeName CDATA #IMPLIED id CDATA #IMPLIED render_style CDATA #IMPLIED text_style CDATA #IMPLIED label CDATA #IMPLIED label_always_on (TRUE|FALSE) "FALSE" marker_size CDATA #IMPLIED radius CDATA #IMPLIED attribute_values CDATA #IMPLIED orient_x CDATA #IMPLIED orient_y CDATA #IMPLIED orient_z CDATA #IMPLIED selectable_in_svg (TRUE|FALSE) "FALSE" onclick CDATA #IMPLIED hidden_info CDATA #IMPLIED >
<geoFeature> elements are used to provide individual geospatial entities to be rendered on a map. The main part of a <geoFeature> element is the geometry (<geometricProperty> element), which must be supplied in compliance with the OGC GML v1.0 Geometry DTD (described in Section 3.6).
typeName is an optional attribute that is ignored by the current release of MapViewer.
id is an optional attribute that can be used to uniquely identify the feature among all the geospatial features on the SVG map. (See the explanation of the selectable_in_svg attribute.) Otherwise, this attribute is ignored by MapViewer.
render_style is an optional attribute. When it is omitted, the geoFeature is not rendered. If it is supplied, its value must be the name of a style stored in the user's USER_SDO_STYLES view.
text_style is an optional attribute. If it is supplied (and if the render_style and label attributes are present and valid), it identifies the style to be used in labeling the feature. If it is not specified, a default text style is used.
label is an optional attribute. If it is supplied (and if the render_style and label attributes are present and valid), it identifies text that is used to label the feature.
label_always_on is an optional attribute. If it is set to TRUE, MapViewer labels the features even if two or more labels will overlap in the display of a theme. (MapViewer always tries to avoid overlapping labels.) If label_always_on is FALSE (the default), when it is impossible to avoid overlapping labels, MapViewer disables the display of one or more labels so that no overlapping occurs. The label_always_on attribute can also be specified for a theme (theme element, described in Section 3.2.20). Specifying label_always_on as TRUE for a feature in the geoFeature element definition gives you control over which features will have their labels displayed if label_always_on is FALSE for a theme and if overlapping labels cannot be avoided.
marker_size is an optional attribute. If it is supplied with a point feature, and if render_style is a marker-type style, the specified size is used by MapViewer in rendering this feature. This provides a mechanism to override the default value specified for a marker style.
radius is an optional attribute. If it is supplied, it specifies a number or a comma-delimited list of numbers, with each number representing the radius of a circle to be drawn centered on this feature. For geodetic data, the unit is meters; for non-geodetic data, the unit is the unit of measurement associated with the data.
attribute_values is an optional attribute. If it is supplied, it specifies a value or a comma-delimited list of values to be used with bucket ranges of an advanced style (for example, values for pie chart segments or bucket values for variable markers).
orient_x and orient_y optionally specify a virtual end point to indicate an orientation vector for rotating a marker symbol (such as a shield symbol to indicate a highway) or text at a specified point. (orient_z is reserved for future use by Oracle.) The value for each must be from -1 to 1. The orientation start point is assumed to be (0,0), and it is translated to the location of the physical point to which it corresponds.
Figure 3-3 illustrates an orientation vector of approximately 34 degrees (counterclockwise from the x-axis), resulting from specifying orient_x="0.3" orient_y="0.2". (To have an orientation that more precisely matches a specific angle, refer to the cotangent or tangent values in the tables in a trigonometry textbook.)
selectable_in_svg is an optional attribute that specifies whether or not the feature is selectable on an SVG map. The default is FALSE; that is, the feature is not selectable on an SVG map. If this attribute is set to TRUE and if theme feature selection is allowed, the feature can be selected by clicking on it. If the feature is selected, its color is changed and its ID is recorded. You can get a list of the ID values of all selected features by calling the JavaScript function getSelectedIdList() defined in the SVG map. (For feature selection to work correctly, the id attribute value of the feature must be set to a value that uniquely identifies it among all the geospatial features on the SVG map.) For information about using JavaScript functions with SVG maps, see Appendix B.
onclick is an optional attribute that specifies the name of the JavaScript function to be called when a user clicks on the feature. The JavaScript function must be defined in the HTML document outside the SVG definition. This function must accept only four parameters: the theme name, the key of the feature, and x and y, which specify the coordinates (in pixels) of the clicked point on the SVG map. For information about using JavaScript functions with SVG maps, see Appendix B.
hidden_info is an optional attribute that specifies an informational note or tip to be displayed when the mouse is moved over the feature. To specify multiple lines, use "\n" between lines. For example, hidden_info="State park with\nhistorical attractions" specifies a two-line tip. (To enable the display of hidden information in the map, you must specify infoon="true" in the <map_request> element, as explained in Section 3.2.1.1.)
The following example shows a <geoFeature> element specification for a restaurant at longitude and latitude coordinates (-78.1234, 41.0346). In this case, the feature will be invisible because the render_style and text_style attributes are not specified.
<geoFeature typeName="Customer" label="PizzaHut in Nashua">
<geometricProperty>
<Point srsName="SDO:8265">
<coordinates>-78.1234,41.0346</coordinates>
</Point>
</geometricProperty>
</geoFeature>
The following example shows a <geoFeature> element specification for a point of interest at longitude and latitude coordinates (-122.2615, 37.5266). The feature will be rendered on the generated map because the render_style attribute is specified. The example specifies some label text (A Place) and a text style for drawing the label text. It also instructs MapViewer to draw two circles, centered on this feature, with radii of 1600 and 4800 meters. (In this case, the srsName attribute of the <Point> element must be present, and it must specify an Oracle Spatial SRID value using the format "SDO:<srid>". Because SRID value 8265 is associated with a geodetic coordinate system, the radius values are interpreted as 1600 and 4800 meters.)
<geoFeature render_style="m.star"
radius="1600,4800"
label="A Place"
text_style="T.Name">
<geometricProperty>
<Point srsName="SDO:8265">
<coordinates>-122.2615, 37.5266</coordinates>
</Point>
</geometricProperty>
</geoFeature>
Figure 3-4 is a map drawn using the <geoFeature> element in the preceding example. The feature is labeled with the text A Place, and it is represented by a red star marker surrounded by two concentric circles.
Figure 3-4 Map with <geoFeature> Element Showing Two Concentric Circles
Description of "Figure 3-4 Map with <geoFeature> Element Showing Two Concentric Circles"
3.2.6 jdbc_georaster_query Element
The <jdbc_georaster_query> element, which is used to define a GeoRaster theme, has the following definition:
<!ELEMENT jdbc_georaster_query (#PCDATA) >
<!ATTLIST jdbc_georaster_query
asis (TRUE|FALSE) "FALSE"
georaster_table CDATA #REQUIRED
georaster_column CDATA #REQUIRED
raster_id CDATA #IMPLIED
raster_table CDATA #IMPLIED
raster_pyramid CDATA #IMPLIED
raster_bands CDATA #IMPLIED
datasource CDATA #IMPLIED
polygon_mask CDATA #IMPLIED
transparent_nodata CDATA #IMPLIED
jdbc_host CDATA #IMPLIED
jdbc_port CDATA #IMPLIED
jdbc_sid CDATA #IMPLIED
jdbc_user CDATA #IMPLIED
jdbc_password CDATA #IMPLIED
jdbc_srid CDATA #IMPLIED
jdbc_mode (thin|oci8) "thin"
>
For detailed usage and reference information about GeoRaster themes, see Section 2.3.4.
3.2.7 jdbc_image_query Element
The <jdbc_image_query> element, which is used to define an image theme (described in Section 2.3.3), has the following definition:
<!ELEMENT jdbc_image_query (#PCDATA) >
<!ATTLIST jdbc_image_query
asis (TRUE|FALSE) "FALSE"
image_format CDATA #REQUIRED
image_column CDATA #REQUIRED
image_mbr_column CDATA #REQUIRED
image_resolution CDATA #IMPLIED
image_unit CDATA #IMPLIED
datasource CDATA #IMPLIED
jdbc_host CDATA #IMPLIED
jdbc_port CDATA #IMPLIED
jdbc_sid CDATA #IMPLIED
jdbc_user CDATA #IMPLIED
jdbc_password CDATA #IMPLIED
jdbc_srid CDATA #IMPLIED
jdbc_mode (thin|oci8) "thin"
>
To define a theme dynamically, you must supply a valid SQL query as the content of the <jdbc_image_query> element. You must specify the JDBC connection information for an image theme (either datasource or the combination of jdbc_host, jdbc_port, jdbc_sid, jdbc_user, and jdbc_password).
jdbc_srid is an optional attribute that specifies the coordinate system (SDO_SRID value) of the data to be rendered.
jdbc_mode identifies the Oracle JDBC driver (thin or oci8) to use to connect to the database.
asis is an optional attribute. If it is set to TRUE, MapViewer does not attempt to modify the supplied query string. If asis is FALSE (the default), MapViewer embeds the SQL query as a subquery of its spatial filter query. For example, assume that you want a map centered at (-122, 37) with size 1, and the supplied query is:
SELECT geometry, sales FROM crm_sales WHERE sales < 100000;
If asis is FALSE, the actual query that MapViewer executes is similar to:
SELECT * FROM (SELECT geometry, sales FROM crm_sales WHERE sales < 100000) WHERE sdo_filter(geometry, sdo_geometry(. . . -122.5, 36.5, -123.5, 37.5 . . .) ='TRUE';
In other words, the original query is further refined by a spatial filter query for the current map window. However, if asis is TRUE, MapViewer executes the query as specified, namely:
SELECT geometry, sales FROM crm_sales WHERE sales < 100000;
image_format identifies the format (such as GIF or JPEG) of the image data. If the image format is not supported by MapViewer, you must create and register a custom image renderer for the format, as explained in Appendix C.
image_column identifies the column of type BLOB where each image is stored.
image_mbr_column identifies the column of type SDO_GEOMETRY where the footprint (minimum bounding rectangle, or MBR) of each image is stored.
image_resolution is an optional attribute that identifies the original image resolution (number of image_unit units for each pixel).
image_unit is an optional attribute, except it is required if you specify the image_resolution attribute. The image_unit attribute specifies the unit of the resolution, such as M for meter. The value for this attribute must be one of the values in the SDO_UNIT column of the MDSYS.SDO_DIST_UNITS table. In Example 2-12 in Section 2.3.3.1, the image resolution is 2 meters per pixel.
For an example of using the <jdbc_image_query> element to specify an image theme, see Example 3-6 in Section 3.1.6.
3.2.8 jdbc_network_query Element
The <jdbc_network_query> element, which is used to define a network theme, has the following definition:
<!ELEMENT jdbc_network_query (#PCDATA) >
<!ATTLIST jdbc_network_query
asis (TRUE|FALSE) "FALSE"
network_name CDATA #REQUIRED
network_level CDATA #IMPLIED
link_style CDATA #IMPLIED
direction_style CDATA #IMPLIED
bidirection_style CDATA #IMPLIED
direction_position CDATA #IMPLIED
direction_markersize CDATA #IMPLIED
direction_multimarker (TRUE|FALSE) "FALSE"
link_labelstyle CDATA #IMPLIED
link_labelcolumn CDATA #IMPLIED
node_style CDATA #IMPLIED
node_markersize CDATA #IMPLIED
node_labelstyle CDATA #IMPLIED
node_labelcolumn CDATA #IMPLIED
path_ids CDATA #IMPLIED
path_styles CDATA #IMPLIED
path_labelstyle CDATA #IMPLIED
path_labelcolumn CDATA #IMPLIED
analysis_algorithm CDATA #IMPLIED
shortestpath_style CDATA #IMPLIED
shortestpath_startnode CDATA #IMPLIED
shortestpath_endnode CDATA #IMPLIED
shortestpath_startstyle CDATA #IMPLIED
shortestpath_endstyle CDATA #IMPLIED
withincost_startnode CDATA #IMPLIED
withincost_style CDATA #IMPLIED
withincost_cost CDATA #IMPLIED
withincost_startstyle CDATA #IMPLIED
datasource CDATA #IMPLIED
jdbc_host CDATA #IMPLIED
jdbc_port CDATA #IMPLIED
jdbc_sid CDATA #IMPLIED
jdbc_user CDATA #IMPLIED
jdbc_password CDATA #IMPLIED
jdbc_srid CDATA #IMPLIED
jdbc_mode (thin|oci8) "thin"
>
For detailed usage and reference information about network themes, see Section 2.3.5.
3.2.9 jdbc_query Element
The <jdbc_query> element is used to define a theme dynamically. This element and its associated <hidden_info> element have the following definitions:
<!ELEMENT jdbc_query (#PCDATA, hidden_info?)>
<!ATTLIST jdbc_query
asis (TRUE|FALSE) "FALSE"
spatial_column CDATA #REQUIRED
key_column CDATA #IMPLIED
label_column CDATA #IMPLIED
label_style CDATA #IMPLIED
render_style CDATA #IMPLIED
x_column CDATA #IMPLIED
y_column CDATA #IMPLIED
datasource CDATA #IMPLIED
jdbc_host CDATA #IMPLIED
jdbc_port CDATA #IMPLIED
jdbc_sid CDATA #IMPLIED
jdbc_user CDATA #IMPLIED
jdbc_password CDATA #IMPLIED
jdbc_srid CDATA #IMPLIED
jdbc_mode (thin|oci8) "thin"
>
<!ELEMENT hidden_info (field+)>
<!ELEMENT field (#PCDATA)>
<!ATTLIST field
column CDATA #REQUIRED
name CDATA #IMPLIED
>
To define a theme dynamically, you must supply a valid SQL query as the content of the <jdbc_query> element. You must specify the spatial_column (column of type SDO_GEOMETRY) and the JDBC connection information for a dynamically defined theme (either datasource or the combination of jdbc_host, jdbc_port, jdbc_sid, jdbc_user, and jdbc_password).
If the selectable_in_svg attribute value is TRUE in the <theme> element, you must use the key_column attribute in the <jdbc_query> element to specify the name of a column that can uniquely identify each selected feature from the JDBC query. The specified column must also appear in the SELECT list in the JDBC query.
render_style and label_style are optional attributes. For render_style, for point features the default is a red cross rotated 45 degrees, for lines and curves it is a black line 1 pixel wide, and for polygons it is a black border with a semitransparent dark gray interior.
x_column and y_column are optional attributes. If specified, they are used to define a point JDBC theme based on two columns in a table, so that MapViewer can render a point theme based on values in these columns. For more information, see Section 2.3.2.1.
jdbc_srid is an optional attribute that specifies the coordinate system (SDO_SRID value) of the data to be rendered.
jdbc_mode identifies the Oracle JDBC driver (thin or oci8) to use to connect to the database.
asis is an optional attribute. If it is set to TRUE, MapViewer does not attempt to modify the supplied query string. If asis is FALSE (the default), MapViewer embeds the SQL query as a subquery of its spatial filter query. For example, assume that you want a map centered at (-122, 37) with size 1, and the supplied query is:
SELECT geometry, sales FROM crm_sales WHERE sales < 100000;
If asis is FALSE, the actual query that MapViewer executes is similar to:
SELECT * FROM (SELECT geometry, sales FROM crm_sales WHERE sales < 100000) WHERE sdo_filter(geometry, sdo_geometry(. . . -122.5, 36.5, -123.5, 37.5. . . ) ='TRUE';
In other words, the original query is further refined by a spatial filter query using the current map window. However, if asis is TRUE, MapViewer executes the query as specified, namely:
SELECT geometry, sales FROM crm_sales WHERE sales < 100000;
The <hidden_info> element specifies the list of attributes from the base table to be displayed when the user moves the mouse over the theme's features. The attributes are specified by a list of <field> elements.
Each <field> element must have a column attribute, which specifies the name of the column from the base table, and it can have a name attribute, which specifies the display name of the column. (The name attribute is useful if you want a text string other than the column name to be displayed.)
For examples of using the <jdbc_query> element to define a theme dynamically, see Example 3-2 in Section 3.1.2 and Example 3-4 in Section 3.1.4.
3.2.10 jdbc_topology_query Element
The <jdbc_topology_query> element, which is used to define a topology theme, has the following definition:
<!ELEMENT jdbc_topology_query (#PCDATA)>
<!ATTLIST jdbc_topology_query
asis (TRUE|FALSE) "FALSE"
topology_name CDATA #REQUIRED
feature_table CDATA #REQUIRED
spatial_column CDATA #REQUIRED
label_column CDATA #IMPLIED
label_style CDATA #IMPLIED
render_style CDATA #IMPLIED
datasource CDATA #IMPLIED
edge_style CDATA #IMPLIED
edge_marker_style CDATA #IMPLIED
edge_marker_size CDATA #IMPLIED
edge_label_style CDATA #IMPLIED
node_style CDATA #IMPLIED
node_label_style CDATA #IMPLIED
face_style CDATA #IMPLIED
face_label_style CDATA #IMPLIED
jdbc_host CDATA #IMPLIED
jdbc_port CDATA #IMPLIED
jdbc_sid CDATA #IMPLIED
jdbc_user CDATA #IMPLIED
jdbc_password CDATA #IMPLIED
jdbc_srid CDATA #IMPLIED
jdbc_mode (thin|oci8) "thin"
>
For detailed usage and reference information about topology themes, see Section 2.3.6.
3.2.11 legend Element
The <legend> element has the following definition:
<!ELEMENT legend (column,themes)? >
<!ATTLIST legend
bgstyle CDATA #implied
font CDATA #implied
location_x CDATA #implied
location_y CDATA #implied
offset_x CDATA #implied
offset_y CDATA #implied
profile (MEDIUM|SMALL|LARGE) "MEDIUM"
position (SOUTH_WEST|SOUTH_EAST|SOUTH|NORTH|
NORTH_WEST|NORTH_EAST|EAST|WEST|CENTER) "SOUTH_WEST"
>
<!ELEMENT column entry+ >
<!ATTLIST entry
is_title (true|false) "false"
is_separator (true|false) "false"
tab CDATA "0"
style CDATA #implied
text CDATA #implied
text_size CDATA #implied
width CDATA #implied
height CDATA #implied
>
<!ELEMENT themes theme+ >
<!ATTLIST theme
name CDATA #REQUIRED
>
<legend> elements are 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 main part of a <legend> element is one or more <column> elements, each of which defines a column in the legend. (If no <column> elements are present, an automatic legend is created, as explained in Section 2.4.2.) A one-column legend will have all entries arranged from top to bottom. A two-column legend will have the two columns side by side, with the first column on the left, and each column having its own legend entries. Figure 2-9 in Section 2.4.2 shows a one-column legend. Figure 3-5 shows a two-column legend.
bgstyle is an optional attribute that specifies the overall background style of the legend. It uses a string with syntax similar to scalable vector graphics (SVG) to specify the fill and stroke colors for the bounding box of the legend. If you specify an opacity (fill-opacity or stroke-opacity) value, the fill and stroke colors can be transparent or partially transparent. The following example specifies a background that is white and half transparent, and a stroke (for the legend box boundary) that is red:
bgstyle="fill:#ffffff;fill-opacity:128;stroke:#ff0000"
font is an optional attribute that specifies the name of the font to be used for text that appears in the legend image. You can specify a logical font name that is supported by Java (serif, sansserif, monospaced, dialog, or dialoginput). You can also specify the name of a physical font that is available on the system where the MapViewer server is running.
location_x and location_y are optional attributes that specify the X and Y coordinates (in screen units) of the start of the legend. If you specify these attributes, they override any specification for the position attribute.
offset_x and offset_y are optional attributes to be used with the position attribute. The default distance from the borders for the position hint corresponds to 10 pixels. You can use these offset parameters to override the default value.
profile is an optional attribute that specifies a relative size of the legend on the map, using one of the following keywords: SMALL, MEDIUM (the default), or LARGE.
position is an optional attribute that specifies where the legend should be drawn on the map. The default is SOUTH_WEST, which draws the legend in the lower-left corner of the resulting map.
is_title is an optional attribute of the <entry> element. When its value is TRUE, the entry is used as the title for the column, which means that the description text appears in a more prominent font than regular legend text, and any other style attribute defined for the entry is ignored. The default is FALSE.
is_separator is an optional attribute of the <entry> element. When its value is TRUE, the entry is used to insert a blank line for vertical spacing in the column. The default is FALSE.
tab is an optional attribute of the <entry> element. It specifies the number of tab positions to indent the entry from the left margin of the column. The default is 0 (zero), which means no indentation.
style is an optional attribute of the <entry> element. It specifies the name of the MapViewer style (such as a color or an image) to be depicted as part of the entry.
text is an optional attribute of the <entry> element. It specifies the description text (for example, a short explanation of the associated color or image) to be included in the entry.
text_size is an optional attribute of the <entry> element. It specifies the size (in display units) of the description text to be included in the entry. The specified value overrides the MapViewer predefined profile size.
width and height are optional attributes that together specify the size (in device units) of the legend entry Any specified values override the defaults, which depend on the MapViewer profile values for small, medium, and large text.
The following example shows the <legend> element specification for the legend in Figure 2-9 in Section 2.4.2.
<legend bgstyle="fill:#ffffff;fill-opacity:128;stroke:#ff0000"
position="NORTH_WEST">
<column>
<entry text="Map Legend" is_title="true"/>
<entry style="M.STAR" text="center point"/>
<entry style="M.CITY HALL 3" text="cities"/>
<entry is_separator="true"/>
<entry style="C.ROSY BROWN STROKE" text="state boundary"/>
<entry style="L.PH" text="interstate highway"/>
<entry text="County population:"/>
<entry style="V.COUNTY_POP_DENSITY" tab="1"/>
</column>
</legend>
In the preceding example:
-
The background color has an opacity value of 128 (
fill-opacity:128), which means that the white background will be half transparent. -
The legend boundary box will be red (
stroke:#ff0000). -
The legend boundary box will be positioned in the upper-left part of the display (
position="NORTH_WEST"). -
The legend will be the default size, because the
profileattribute (which has a default value ofMEDIUM) is not specified. -
The legend will have a single column, with entries arranged from top to bottom.
-
The first entry is the legend title, with the text Map Legend.
-
The fourth entry is a separator for adding a blank line.
-
The seventh entry is description text (County population:) that users of the generated map will associate with the next (and last) entry, which specifies an advanced style. The County population: text entry is helpful because advanced styles usually have their own descriptive text, and you do not want users to become confused about which text applies to which parts of the legend.
-
The last entry specifies an advanced style (
style="V.COUNTY_POP_DENSITY"), and it is indented one tab position (tab="1") so that the colors and text identifying various population density ranges will be easy for users to distinguish from the preceding County population: description text.
3.2.12 map_tile_theme Element
The <map_tile_theme> element is used to define a map tile theme, which produces a map image layer rendered by the map tile server with pregenerated map image tiles. The map image tiles can be served by any internal or external map service providers. This element has the following definition:
<!ELEMENT map_tile_theme (#PCDATA)>
<!ATTLIST map_tile_theme
map_tile_layer CDATA # REQUIRED
snap_to_tile_scale (TRUE|FALSE) "FALSE"
>
map_tile_name specifies the name of the map tile layer that has been predefined with MapViewer.
snap_to_tile_scale is an optional attribute that specifies whether to adjust the map scale to fit that of one of the predefined map tile layer zoom levels. If this attribute is FALSE, the scale of the result map is always the same as what the map request specifies; and if the map request scale does not fit any of the predefined map tile layer zoom levels, the map tile images are scaled to fit the map request scale. If this attribute is TRUE, the scale of the result map is adjusted to fit one of the predefined map tile layer zoom levels when the request map scale does not fit any of the predefined zoom levels.
3.2.13 north_arrow Element
The <north_arrow> element specifies a style (usually a marker) to point to the north direction on the map. It uses the map request rotation attribute to define its orientation. This element has the following definition:
<!ELEMENT north_arrow (style, location?, size?) >
The <style> element specifies the name of the style (typically a marker style) for the north arrow.
The <location> element is optional. It specifies the X and Y coordinate values (in pixels) of the position on the map for the north arrow. The default value is (25, 25).
The <size> element is optional. It specifies the width and height (in pixels) to be used by MapViewer in rendering the north arrow. The default value is (16, 32).
Example 3-20 shows a north arrow definition using style m.image41_bw, located at position (35, 35) of the map image, and with width 16 and height 32.
3.2.14 operation Element
The <operation> element enables you to perform additional transformations on the original data during rendering. The <operation> element has the following definition:
<!ELEMENT operation (parameter+) > <!ATTLIST parameter name CDATA #REQUIRED >
Currently this element is used in GeoRaster themes (described in Section 2.3.4). You can perform some image processing operations on the original image, such as normalization, equalization, linear stretch, piecewise linear stretch, brightness and contrast adjustment, and threshold change.
Example 3-21 specifies the normalization operation with a GeoRaster theme.
Example 3-21 Normalization Operation with a GeoRaster Theme
<theme name="geor_theme" >
<jdbc_georaster_query
jdbc_srid="0"
datasource="mvdemo"
georaster_table="dem"
georaster_column="georaster"
asis="false"> select georaster from dem
</jdbc_georaster_query>
<operations>
<operation name="normalize">
</operation>
</operations>
</theme>
The following code segment shows a manual linear stretch operation. (For automatic linear stretch, include the <operation> element but no <parameter> elements.)
<operation name="linearstretch">
<parameter name="autostretch" value="false"/>
<parameter name="lowstretch" value="50"/>
<parameter name="highstretch" value="150"/>
</operation>
Table 3-1 lists the image processing operations, their <operation> element name keyword values, and (where relevant) associated <parameter> element values.
Table 3-1 Image processing Options for GeoRaster Theme Operations
| Operation | <operation> name value | <parameter> values |
|---|---|---|
|
Normalization |
|
(Not applicable) |
|
Equalization |
|
(Not applicable) |
|
Linear stretch |
|
|
|
Piecewise linear stretch |
|
(Not applicable) |
|
Brightness |
|
|
|
Contrast |
|
|
|
Change threshold |
|
|
3.2.15 operations Element
The <operations> element specifies one or more <operation> elements (described in Section 3.2.14). The <operations> element has the following definition:
<!ELEMENT operations (oepration+) >
For a predefined GeoRaster theme, the <operations> element will be part of the styling rule definition. Example 3-21 shows the styling rules for a GeoRaster theme that uses the normalization operation.
3.2.16 parameter Element
The <parameter> element defines values to be used in an operation to be applied on themes. (The operation is specified in an <operations> element, described in Section 3.2.14.) The <parameter> element has the following definition:
<!ELEMENT parameter > <!ATTLIST parameter name CDATA #REQUIRED value CDATA #REQUIRED >
Each parameter must have a name and value associated with it.
3.2.17 scale_bar Element
The <scale_bar> element defines a scale bar (to show how many kilometers or miles are represented by a distance marked on the bar) to be added to the map request, if the map has a known spatial reference system (SRS). You can specify a single display mode (Metric or US) or dual mode (both Metric and US). The <scale_bar> element has the following definition:
<!ELEMENT scale_bar >
<!ATTLIST scale_bar
mode (METRIC_MODE|US_MODE|DUAL_MODES) "METRIC_MODE"
position (SOUTH_WEST|SOUTH_EAST|SOUTH|NORTH|
NORTH_WEST|NORTH_EAST) "NORTH_EAST"
offset_y CDATA #implied
offset_y CDATA #implied
color1 CDATA #implied
color1_opacity CDATA #implied
color2 CDATA #implied
color2_opacity CDATA #implied
length_hint CDATA #implied
label_color CDATA #implied
label_font_family CDATA #implied
label_font_size CDATA #implied
label_halo_size CDATA #implied
label_position (TOP|BOTTOM) "TOP"
>
All <scale_bar> attributes are optional.
mode specifies if the scale bar should be in metric or US mode, or in both modes. The default is METRIC_MODE.
position defines the relative location on the map to place the scale bar. The default is NORTH_EAST.
offset_x and offset_y define the X and Y values to offset the scale bar position from the map margin. The default value for each is 0.
color1, color1_opacity, color2, and color2_opacity define the colors to be used when rendering the scale bar. color1 and color2 have a default value for red, green, blue; color1_opacity has a default value of (0x44, 0x44, 0x44, 210); and color 2_opacity has a default value of (0xee, 0xee, 0xee, 210).
length_hint defines the preferred number of pixels to be used to render the scale bar. The default is approximately 17% of the map width.
label_color, label_font_family, label_font_size, and label_halo_size affect the scale bar text. The defaults are black color, Serif font family, 12pt font size, and no halo (0 halo size).
label_position defines the position of the text relative to the scale bar (TOP or BOTTOM). The default is TOP.
Example 3-23 defines a scale bar.
3.2.18 style Element
The <style> element has the following definition:
<!ELEMENT style (svg | AdvancedStyle)?>
<!ATTLIST style
name CDATA #REQUIRED
>
The <style> element lets you specify a dynamically defined style. The style can be either of the following:
-
An SVG description representing a color, line, marker, area, or text style
-
An advanced style definition (see Section A.6) representing a bucket, a color scheme, or a variable marker style
The name attribute identifies the style name.
The following example shows an excerpt that dynamically defines two styles (a color style and an advanced style) for a map request:
<map_request . . .>
. . .
<styles>
<style name="color_red">
<svg width="1in" height="1in">
<g class="color"
style="stroke:red;stroke-opacity:100;fill:red;fill-opacity:100">
<rect width="50" height="50"/>
</g>
</svg>
</style>
<style name="ranged_bucket_style">
<AdvancedStyle>
<BucketStyle>
<Buckets>
<RangedBucket seq="0" label="less than 100k"
high="100000.0" style="C.RB13_13"/>
<RangedBucket seq="1" label="100k - 150k" low="100000.0"
high="150000.0" style="C.RB13_1"/>
<RangedBucket seq="2" label="150k - 250k" low="150000.0"
high="250000.0" style="C.RB13_4"/>
<RangedBucket seq="3" label="250k - 350k" low="250000.0"
high="350000.0" style="C.RB13_7"/>
<RangedBucket seq="4" label="350k - 450k" low="350000.0"
high="450000.0" style="C.RB13_10"/>
</Buckets>
</BucketStyle>
</AdvancedStyle>
</style>
</styles>
</map_request>
3.2.19 styles Element
The <styles> element has the following definition:
<!ELEMENT styles (style+) >
The <styles> element specifies one or more <style> elements (described in Section 3.2.18).
3.2.20 theme Element
The <theme> element has the following definition:
<!ELEMENT theme (jdbc_query | jdbc_image_query | jdbc_georaster_query
| jdbc_network_query | jdbc_topology_query | map_tile_theme)?,
operations? >
<!ATTLIST theme
name CDATA #REQUIRED
datasource CDATA #IMPLIED
template_theme CDATA #IMPLIED
max_scale CDATA #IMPLIED
min_scale CDATA #IMPLIED
label_max_scale CDATA #IMPLIED
label_min_scale CDATA #IMPLIED
label_always_on (TRUE|FALSE) "FALSE"
fast_unpickle (TRUE|FALSE) "TRUE"
mode CDATA #IMPLIED
min_dist CDATA #IMPLIED
fixed_svglabel (TRUE|FALSE) "FALSE"
visible_in_svg (TRUE|FALSE) "TRUE"
selectable_in_svg (TRUE|FALSE) "FALSE"
part_of_basemap (TRUE|FALSE) "FALSE"
simplify_shapes (TRUE|FALSE) "TRUE"
transparency CDATA #IMPLIED
minimum_pixels CDATA #IMPLIED
onclick CDATA #IMPLIED
onmousemove CDATA #IMPLIED
onmouseover CDATA #IMPLIED
onmouseout CDATA #IMPLIED
workspace_name CDATA #IMPLIED
workspace_savepoint CDATA #IMPLIED
workspace_date CDATA #IMPLIED
workspace_date_format CDATA #IMPLIED
fetch_size CDATA #IMPLIED
timeout CDATA #IMPLIED
>
The <theme> element lets you specify a predefined or dynamically defined theme.
-
For a predefined theme, whose definition is already stored in your USER_SDO_THEMES view, only the theme name is required.
-
For a dynamically defined theme, you must provide the information in one of the following elements:
<jdbc_query>(described in Section 3.2.9),<jdbc_image_query>(described in Section 3.2.7),<jdbc_georaster_query>(described in Section 2.3.4),<jdbc_network_query>(described in Section 2.3.5), or<jdbc_topology_query>(described in Section 2.3.6). -
For a GeoRaster theme, you can define some image processing options (described in Section 3.2.14).
The name attribute identifies the theme name. For a predefined theme, the name must match a value in the NAME column of the USER_SDO_THEMES view (described in Section 2.9.2). For a dynamically defined theme, this is just a temporary name for referencing the jdbc_query-based theme.
datasource is an optional attribute that specifies a data source for the theme. If you do not specify this attribute, the data source for the map request is assumed (see the datasource attribute explanation in Section 3.2.1.1). By specifying different data sources for different themes, you can use multiple data sources in a map request.
template_theme is an optional attribute that can be used to render two or more themes when a predefined theme has same name in multiple data sources. You cannot repeat theme names in a map request, but if you have two different data sources with same predefined theme name, you can use this attribute to render both themes. The following example specifies two themes that are based on a US_STATES theme that exists in two data sources, but that has a different content in each data source.
<themes> <theme name="US_STATES" datasource="dsrc"/> <theme name="OTHER_US_STATES" template_theme="US_STATES" datasource="other_dsrc" /> </themes>
The max_scale and min_scale attributes affect the visibility of this theme. If max_scale and min_scale are omitted, the theme is always rendered, regardless of the map scale. (See Section 2.4.1 for an explanation of max_scale and min_scale.)
The label_max_scale and label_min_scale attributes affect the visibility of feature labels of this theme. If label_max_scale and label_min_scale are omitted, the theme feature labels are always rendered when the map scale is within the visible range of theme scales (that is, within the max_scale and min_scale range). (See Section 2.4.1 for an explanation of label_max_scale and label_min_scale.)
label_always_on is an optional attribute. If it is set to TRUE, MapViewer labels all features of the theme even if two or more labels will overlap in the display. (MapViewer always tries to avoid overlapping labels.) If label_always_on is FALSE (the default), when it is impossible to avoid overlapping labels, MapViewer disables the display of one or more labels so that no overlapping occurs. The label_always_on attribute can also be specified for a map feature (geoFeature element, described in Section 3.2.5), thus allowing you to control which features will have their labels displayed if label_always_on is FALSE for a theme and if overlapping labels cannot be avoided.
fast_unpickle is an optional attribute. If it is TRUE (the default), MapViewer uses its own fast unpickling (unstreaming) algorithm instead of the generic JDBC conversion algorithm to convert SDO_GEOMETRY objects fetched from the database into a Java object accessible to MapViewer. This process improves performance, but occasionally the coordinates may lose some precision (around 0.00000005), which can be significant in applications where all precision digits of each coordinate must be kept. If fast_unpickle is set to FALSE, MapViewer uses the generic JDBC conversion algorithm. This process is slower than MapViewer's fast unpickling process, but there is never any loss of precision.
mode is an optional attribute. For a topology theme, you can specify mode="debug" to display edges, nodes, and faces, as explained in Section 2.3.6. The mode attribute is ignored for other types of themes.
min_dist is an optional attribute. It specifies the minimum on-screen distance (number of pixels) between two adjacent shape points on a line string or polygon for rendering of separate shape points. If the on-screen distance between two adjacent shape points is less than the min_dist value, only one shape point is rendered. The default value is 0.5. You can specify higher values to reduce the number of shape points rendered on an SVG map, and thus reduce the size of the resulting SVG file. You can specify different values in different theme definitions, to allow for customized levels of detail in SVG maps.
fixed_svglabel is an optional attribute that specifies whether to display the labels on an SVG map using the original "fixed" labels, but having them appear larger or smaller as the zoom level increases (zoomin) or decreases (zoomout), or to use different labels with the same text but different actual sizes so that the apparent size of each label remains the same at all zoom levels. If the fixed_svglabel value is specified as TRUE, the same theme labels are displayed on the map at all zoom levels, with the labels zoomed in and out as the map is zoomed in and out. If the value is FALSE (the default), different theme labels are displayed at different zoom levels so that the size of each displayed label appears not to change during zoomin and zoomout operations.
visible_in_svg is an optional attribute that specifies whether or not to display the theme on an SVG map. If its value is TRUE (the default), the theme is displayed; if it is set to FALSE, the theme is not displayed. However, even if this attribute is set to FALSE, the theme is still rendered to the SVG map: the theme is initially invisible, but you can make it visible later by calling the JavaScript function showTheme() defined in the SVG map. For information about using JavaScript functions with SVG maps, see Appendix B.
selectable_in_svg is an optional attribute that specifies whether or not the theme is selectable on an SVG map. The default is FALSE; that is, the theme is not selectable on an SVG map. If this attribute is set to TRUE and if theme feature selection is allowed, each feature of the theme displayed on the SVG map can be selected by clicking on it. If the feature is selected, its color is changed and its ID (its rowid by default) is recorded. You can get a list of the ID values of all selected features by calling the JavaScript function getSelectedIdList() defined in the SVG map. For information about using JavaScript functions with SVG maps, see Appendix B.
part_of_basemap is an optional attribute. If the map format is SVG and the value of this attribute is TRUE, MapViewer renders the theme as part of and on top of the base map, which is rendered as a raster image.
simplify_shapes is an optional attribute that specifies whether or not the shapes are simplified before being rendered. Simplification is useful when you want a map display with less fine resolution than the original geometries. For example, if the display resolution cannot show the hundreds or thousands of turns in the course of a river or in a political boundary, better performance might result if the shapes were simplified to show only the major turns. The default is TRUE; that is, shapes are simplified before being rendered. If this attribute is set to FALSE, MapViewer attempts to render all vertices and line segments from the original geometries, and performance may be slower.
transparency is an optional parameter to define the basic alpha composing value to be applied on themes during rendering. The value can be from 0 to 1, with 0 meaning completely transparent and 1 (the default) meaning completely opaque (no transparency).
minimum_pixels is an optional parameter that defines the level of resolution to be used on the spatial filter query. This may be useful to avoid rendering too many elements at the same position of the screen. (See the Oracle Spatial documentation about the min_resolution and max_resolution options for the SDO_FILTER operator.) The unit for minimum_pixels is screen pixels. For example, minimum_pixels=1 means that the spatial filter query will not return features with a resolution less than the amount that 1 pixel represents for the current device window and current query window
onclick is an optional attribute that specifies the name of the JavaScript function to be called when a user clicks on an SVG map and theme feature selection is allowed (see the selectable_in_svg attribute explanation). The JavaScript function must be defined in the HTML document that has the SVG map embedded. This function must accept only four parameters: the theme name, the key of the feature, and x and y, which specify the coordinates (in pixels) of the clicked point on the SVG map. 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 top of any feature of the theme on an SVG map. The JavaScript function must be defined in the HTML document that has the SVG map embedded. This function must accept only four parameters: the theme name, the key of the feature, and x and y, which specify the coordinates (in pixels) of the point for the move on the SVG map. For information about using JavaScript functions with SVG maps, see Appendix B.
onmouseover is an optional attribute that specifies the name of the JavaScript function to be called when a user moves the mouse into a feature of the theme on an SVG map. (Unlike the onmousemove function, which is called whenever the mouse moves inside the theme, the onmouseover function is called only once when the mouse moves from outside a feature of the theme to inside a feature of the theme.) The JavaScript function must be defined in the HTML document that has the SVG map embedded. This function must accept only four parameters: the theme name, the key of the feature, and x and y, which specify the coordinates (in pixels) of the point at which the mouse moves inside a feature on the SVG map. For information about using JavaScript functions with SVG maps, see Appendix B.
onmouseout is an optional attribute that specifies the name of the JavaScript function to be called when a user moves the mouse out of a feature of the theme on an SVG map. The JavaScript function must be defined in the HTML document that has the SVG map embedded. This function must accept only four parameters: the theme name, the key of the feature, and x and y, which specify the coordinates (in pixels) of the point at which the mouse moves out of a feature on the SVG map. For information about using JavaScript functions with SVG maps, see Appendix B.
workspace_name, workspace_savepoint, workspace_date, and workspace_date_format are optional attributes related to support for Workspace Manager in Mapviewer, which is explained in Section 2.8.
fetch_size is an optional attribute that specifies how many rows will be prefetched into memory. The default value is 100.
timeout is an optional attribute that specifies the number of milliseconds to wait for the connection to the WMS or WFS server.
3.2.21 themes Element
The <themes> element has the following definition:
<!ELEMENT themes (theme+) >
The <themes> element specifies one or more <theme> elements (described in Section 3.2.20). If you have specified a base map (basemap attribute of the map_request element), any themes that you specify in a <themes> element are plotted after those defined in the base map. If no base map is specified, only the specified themes are rendered.
Inside this <themes> element there must be one or more <theme> child elements, which are rendered in the order in which they appear.
3.2.22 theme_modifiers Element
The <theme_modifiers> element has the following definition:
<!ELEMENT theme_modifiers (theme_decorations)? >
The theme modifiers enable you to override the theme definition on a base map, without having to edit and change the base map definition. The <theme_decorations> element has the same attributes as the <theme> element (described in Section 3.2.20).
The following example overrides the labels_always_on attribute for the theme_us_airport theme on the base map FORCED_LABELING.
<?xml version="1.0" standalone="yes"?>
<map_request
title="Override labeling on map definition"
basemap="FORCED_LABELING"
datasource="tilsmenv"
width="500"
height="375"
bgcolor="#a6caf0"
antialiase="true"
format="PNG_URL">
<center size="15.0">
<geoFeature>
<geometricProperty typeName="center">
<Point>
<coordinates>-122.4,37.8</coordinates>
</Point>
</geometricProperty>
</geoFeature>
</center>
<theme_modifiers>
<theme_decorations name="theme_us_airport" label_always_on="false"/>
</theme_modifiers>
</map_request>
3.3 Information Request DTD
In addition to issuing map requests (see Section 3.2) and administrative requests (see Chapter 7), you can issue information requests to MapViewer. An information request is an XML request string that you can use to execute SQL queries and obtain the result as an array of strings or an XML document. The SQL query must be a SELECT statement and must select only primitive SQL types (for example, not LOB types or user-defined object types).
The following is the DTD for a MapViewer information request.
<!ELEMENT info_request (#PCDATA) >
<!ATTLIST info_request
datasource CDATA #REQUIRED
format (strict | non-strict) "strict"
>
datasource is a required attribute that specifies the data source for which to get the information.
format is an optional attribute. If it is strict (the default), all rows are formatted and returned in an XML document. If format is set to non-strict, all rows plus a column heading list are returned in a comma-delimited text string.
Example 3-24 shows an information request to select the city, 1990 population, and state abbreviation from the CITIES table, using the connection information in the mvdemo data source and returning the information as an XML document (format="strict").
Example 3-24 MapViewer Information Request
<?xml version="1.0" standalone="yes"?>
<info_request datasource="mvdemo" format="strict">
SELECT city, pop90 population, state_abrv state FROM cities
</info_request>
Example 3-24 returns an XML document that includes the following:
<?xml version="1.0" encoding="UTF-8"?>
<ROWSET>
<ROW num="1">
<CITY>New York</CITY>
<POPULATION>7322564</POPULATION>
<STATE>NY</STATE>
</ROW>
<ROW num="2">
<CITY>Los Angeles</CITY>
<POPULATION>3485398</POPULATION>
<STATE>CA</STATE>
</ROW>
<ROW num="3">
<CITY>Chicago</CITY>
<POPULATION>2783726</POPULATION>
<STATE>IL</STATE>
</ROW>
<ROW num="4">
<CITY>Houston</CITY>
<POPULATION>1630553</POPULATION>
<STATE>TX</STATE>
</ROW>
. . .
</ROWSET>
3.4 Map Response DTD
The following is the DTD for the map response resulting from normal processing of a map request. (Section 3.5 shows the DTD for the response if there was an exception or unrecoverable error.)
<!ELEMENT map_response (map_image)>
<!ELEMENT map_image (map_content, box, themes, WMTException)>
<!ELEMENT map_content EMPTY>
<!ATTLIST map_content url CDATA #REQUIRED>
<!ELEMENT WMTException (#PCDATA)>
<!ATTLIST WMTException version CDATA "1.0.0"
error_code (SUCCESS|FAILURE) #REQUIRED
>
The response includes the URL for retrieving the image, as well as any error information. When a valid map is generated, its minimum bounding box is also returned, along with the list of themes that have features within the minimum bounding rectangle (MBR) that intersects with the bounding box.
Example 3-25 shows a map response.
<?xml version="1.0" encoding="UTF-8" ?>
<map_response>
<map_image>
<map_content url="http://map.oracle.com/output/map029763.gif"/>
<box srsName="default">
<coordinates>-122.260443,37.531621 -120.345,39.543</coordinates>
</box>
<themes>
<theme name="US_STATES" />
<theme name="US_HIGHWAYS" />
</themes>
<WMTException version="1.0.0" error_code="SUCCESS">
</WMTException>
</map_image>
</map_response>
3.5 MapViewer Exception DTD
The following DTD is used by the output XML when an exception or unrecoverable error is encountered while processing a map request:
<!ELEMENT oms_error (#PCDATA)>
The exception or error message is embedded in this element.
3.6 Geometry DTD (OGC)
MapViewer supports the Geometry DTD as defined in the Open Geospatial Consortium (OGC) GML v1.0 specification. This specification and other, more recent, versions are available at the following URL:
http://www.opengeospatial.org/specs/
This specification has the following copyright information:
Copyright © 2000 OGC All Rights Reserved.
This specification includes the following status information, although its current official status is Deprecated Recommendation Paper:
This document is an OpenGIS® Consortium Recommendation Paper. It is similar to a proposed recommendation in other organizations. While it reflects a public statement of the official view of the OGC, it does not have the status of a OGC Technology Specification. It is anticipated that the position stated in this document will develop in response to changes in the underlying technology. Although changes to this document are governed by a comprehensive review procedure, it is expected that some of these changes may be significant. The OGC explicitly invites comments on this document. Please send them to gml.rfc@opengis.org
The following additional legal notice text applies to this specification:
THIS DOCUMENT IS PROVIDED "AS IS," AND COPYRIGHT HOLDERS MAKE NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, OR TITLE; THAT THE CONTENTS OF THE DOCUMENT ARE SUITABLE FOR ANY PURPOSE; NOR THAT THE IMPLEMENTATION OF SUCH CONTENTS WILL NOT INFRINGE ANY THIRD PARTY PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER RIGHTS COPYRIGHT HOLDERS WILL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF ANY USE OF THE DOCUMENT OR THE PERFORMANCE OR IMPLEMENTATION OF THE CONTENTS THEREOF.
The OGC Geometry DTD in this specification is as follows:
<!-- ============================================================== --> <!-- G e o g r a p h y --> <!-- M a r k u p --> <!-- L a n g u a g e --> <!-- --> <!-- ( G M L ) --> <!-- --> <!-- G E O M E T R Y D T D --> <!-- --> <!-- Copyright (c) 2000 OGC All Rights Reserved. --> <!-- ============================================================== --> <!-- the coordinate element holds a list of coordinates as parsed character data. Note that it does not reference a SRS and does not constitute a proper geometry class. --> <!ELEMENT coordinates (#PCDATA) > <!ATTLIST coordinates decimal CDATA #IMPLIED cs CDATA #IMPLIED ts CDATA #IMPLIED > <!-- the Box element defines an extent using a pair of coordinates and a SRS name. --> <!ELEMENT Box (coordinates) > <!ATTLIST Box ID CDATA #IMPLIED srsName CDATA #REQUIRED > <!-- ============================================================== --> <!-- G E O M E T R Y C L A S S D e f i n i t i o n s --> <!-- ============================================================== --> <!-- a Point is defined by a single coordinate. --> <!ELEMENT Point (coordinates) > <!ATTLIST Point ID CDATA #IMPLIED srsName CDATA #IMPLIED > <!-- a LineString is defined by two or more coordinates, with linear interoplation between them. --> <!ELEMENT LineString (coordinates) > <!ATTLIST LineString ID CDATA #IMPLIED srsName CDATA #IMPLIED > <!-- a Polygon is defined by an outer boundary and zero or more inner boundaries. These boundaries are themselves defined by LinerRings. --> <!ELEMENT Polygon (outerBoundaryIs, innerBoundaryIs*) > <!ATTLIST Polygon ID CDATA #IMPLIED srsName CDATA #IMPLIED > <!ELEMENT outerBoundaryIs (LinearRing) > <!ELEMENT innerBoundaryIs (LinearRing) > <!-- a LinearRing is defined by four or more coordinates, with linear interpolation between them. The first and last coordinates must be coincident. --> <!ELEMENT LinearRing (coordinates) > <!ATTLIST LinearRing ID CDATA #IMPLIED > <!-- a MultiPoint is defined by zero or more Points, referenced through a pointMember element. --> <!ELEMENT MultiPoint (pointMember+) > <!ATTLIST MultiPoint ID CDATA #IMPLIED srsName CDATA #IMPLIED > <!ELEMENT pointMember (Point) > <!-- a MultiLineString is defined by zero or more LineStrings, referenced through a lineStringMember element. --> <!ELEMENT MultiLineString (lineStringMember+) > <!ATTLIST MultiLineString ID CDATA #IMPLIED srsName CDATA #IMPLIED > <!ELEMENT lineStringMember (LineString) > <!-- a MultiPolygon is defined by zero or more Polygons, referenced through a polygonMember element. --> <!ELEMENT MultiPolygon (polygonMember+) > <!ATTLIST MultiPolygon ID CDATA #IMPLIED srsName CDATA #IMPLIED > <!ELEMENT polygonMember (Polygon) > <!-- a GeometryCollection is defined by zero or more geometries, referenced through a geometryMember element. A geometryMember element may be any one of the geometry classes. --> <!ENTITY % GeometryClasses "( Point | LineString | Polygon | MultiPoint | MultiLineString | MultiPolygon | GeometryCollection )" > <!ELEMENT GeometryCollection (geometryMember+) > <!ATTLIST GeometryCollection ID CDATA #IMPLIED srsName CDATA #IMPLIED > <!ELEMENT geometryMember %GeometryClasses; > <!-- ============================================================== --> <!-- G E O M E T R Y P R O P E R T Y D e f i n i t i o n s --> <!-- ============================================================== --> <!-- GML provides an 'endorsed' name to define the extent of a feature. The extent is defined by a Box element, the name of the property is boundedBy. --> <!ELEMENT boundedBy (Box) > <!-- the generic geometryProperty can accept a geometry of any class. --> <!ELEMENT geometryProperty (%GeometryClasses;) > <!-- the pointProperty has three descriptive names: centerOf, location and position. --> <!ELEMENT pointProperty (Point) > <!ELEMENT centerOf (Point) > <!ELEMENT location (Point) > <!ELEMENT position (Point) > <!-- the lineStringProperty has two descriptive names: centerLineOf and edgeOf. --> <!ELEMENT lineStringProperty (LineString) > <!ELEMENT centerLineOf (LineString)> <!ELEMENT edgeOf (LineString)> <!-- the polygonProperty has two descriptive names: coverage and extentOf. --> <!ELEMENT polygonProperty (Polygon) > <!ELEMENT coverage (Polygon)> <!ELEMENT extentOf (Polygon)> <!-- the multiPointProperty has three descriptive names: multiCenterOf, multiLocation and multiPosition. --> <!ELEMENT multiPointProperty (MultiPoint) > <!ELEMENT multiCenterOf (MultiPoint) > <!ELEMENT multiLocation (MultiPoint) > <!ELEMENT multiPosition (MultiPoint) > <!-- the multiLineStringProperty has two descriptive names: multiCenterLineOf and multiEdgeOf. --> <!ELEMENT multiLineStringProperty (MultiLineString) > <!ELEMENT multiCenterLineOf (MultiLineString) > <!ELEMENT multiEdgeOf (MultiLineString) > <!-- the multiPolygonProperty has two descriptive names: multiCoverage and multiExtentOf. --> <!ELEMENT multiPolygonProperty (MultiPolygon) > <!ELEMENT multiCoverage (MultiPolygon) > <!ELEMENT multiExtentOf (MultiPolygon) > <!ELEMENT geometryCollectionProperty (GeometryCollection) > <!-- ============================================================== --> <!-- F E A T U R E M E T A D A T A D e f i n i t i o n s --> <!-- ============================================================== --> <!-- Feature metadata, included in GML Geometry DTD for convenience; name and description are two 'standard' string properties defined by GML. --> <!ELEMENT name (#PCDATA)> <!ELEMENT description (#PCDATA)>