Oracle® Application Server MapViewer User's Guide
10g Release 2 (10.1.2) Part No. B14036-01 |
|
![]() Previous |
![]() Next |
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 6.)
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:
hostname
is the network path of the server on which MapViewer is running.
port
is the port on which the Web server listens.
MapViewer-servlet-path
is the MapViewer servlet path (for example, mapviewer/omserver
).
xml-request
is the URL-encoded XML request submitted using the HTML GET
or POST
method.
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 Definition Tool, which is described in Chapter 7.
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:
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"
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.)
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>
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 basemap
is 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.MOTEL
style and the label Motel 1
in the T.MOTEL
style.
A circle with a radius of 300 meters will be drawn around the center.
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="tiger" 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.14 and Section 3.2.9.
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>
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.5.)
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 renderImages
method, 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.
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.
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>
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 pieradius
attribute specifies the size of each pie chart in pixels. Each slice (<PieSlice>
element) has a color defined for it. The name
attribute 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 specifies style="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. The column
attribute value can be dummy
or any other string, and the value must be enclosed on both sides by two single quotation marks.
Because the V.PIECHART1
style 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_CHART
theme 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.
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>
Example 3-11 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-11 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); } }
Example 3-12 is a sample PL/SQL program that sends an XML request to the MapViewer server. This example works only on Oracle Database release 9.0.1 and later.
Example 3-12 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; /
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?, 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| 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 rasterbasemap (TRUE|FALSE) "FALSE" onrectselect CDATA #IMPLIED onpolyselect CDATA #IMPLIED > <!ELEMENT center (geoFeature)> <!ATTLIST center size CDATA #REQUIRED > <!ELEMENT bounding_themes (#PCDATA) > <!ATTLIST bounding_themes border_margin CDATA #IMPLIED preserve_aspect_ratio CDATA "TRUE" > <!ELEMENT srs (#PCDATA) > <!ELEMENT themes (theme+) > <!ELEMENT theme (jdbc_query | jdbc_image_query | jdbc_georaster_query | jdbc_network_query | jdbc_topology_query )? > <!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" onclick 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 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 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 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_separator (true|false) "false" tab CDATA "0" style CDATA #implied text CDATA #implied >
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:
The <map_request>
element has the following definition:
<!ELEMENT map_request ((box | center | bounding_themes)?, srs?, legend?, themes?, styles?, geoFeature*)>
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.15) specifies predefined or dynamically defined themes.
The optional <styles>
element (see Section 3.2.13) 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.
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.
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| 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 rasterbasemap (TRUE|FALSE) "FALSE" onrectselect CDATA #IMPLIED onpolyselect 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.8.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.
antialiasing
is an optional attribute. When its value is TRUE
, MapViewer renders the map image in an antialiased manner. This usually provides a map with better graphic quality, but it may take longer for the map to be generated. The default value is FALSE
(for faster map generation). (For backward compatibility, antialiase
is a synonym for antialiasing
, but you are encouraged to use antialiasing
.)
imagescaling
is an optional attribute. When its value is TRUE
(the default), MapViewer attempts to scale the images to fit the current querying window and the generated map image size. When its value is FALSE
, and if an image theme is included directly or indirectly (such as through a base map), the images from the image theme are displayed in their original resolution. This attribute has no effect when no image theme is involved in a map request.
format
is an optional attribute that specifies the file format of the returned map image. The default value is GIF_URL
, which is a URL to a GIF image stored on the MapViewer host system.
If you specify GIF
, the generated GIF image data is embedded in a MapResponse
object and returned to the client. If you specify GIF_STREAM
, the generated image map content is returned directly to the client through the HTTP MIME type image/gif
.
If you specify JAVA_IMAGE
, a Java 2D BufferedImage
object with a color model of TYPE_INT_RGB
is embedded in a MapResponse
object and returned to the client.
If you specify PNG_STREAM
, the stream of the image in nonindexed PNG format is returned directly; if you specify PNG_URL
, a URL to a nonindexed PNG image stored on the MapViewer host system is returned. (The PNG image format has some advantages over the GIF format, including faster image encoding and true color support.)
If you specify PNG8_STREAM
, the stream of the image in indexed PNG format is returned directly; if you specify PNG8_URL
, a URL to an indexed PNG image stored on the MapViewer host system is returned. (The PNG image format has some advantages over the GIF format, including faster image encoding and true color support. The indexed PNG format limits the total number of colors available for displaying the map to 256.)
If you specify JPEG_STREAM
, the stream of the image in JPEG format is returned directly; if you specify JPEG_URL
, a URL to a JPEG image stored on the MapViewer host system is returned.
If you specify SVG_STREAM
, the stream of the image in SVG Basic (SVGB) format is returned directly; if you specify SVG_URL
, a URL to an SVG Basic image stored on the MapViewer host system is returned.
If you specify SVGZ_STREAM
, the stream of the image in SVG Compressed (SVGZ) format is returned directly; if you specify SVGZ_URL
, a URL to an SVG Compressed image stored on the MapViewer host system is returned. SVG Compressed format can effectively reduce the size of the SVG map by 40 to 70 percent compared with SVG Basic format, thus providing better performance.
If you specify SVGTINY_STREAM
, the stream of the image in SVG Tiny (SVGT) format is returned directly; if you specify SVGTINY_URL
, a URL to an SVG Tiny image stored on the MapViewer host system is returned. (The SVG Tiny format is designed for devices with limited display capabilities, such as cell phones.)
transparent
is an optional attribute that applies to indexed PNG (PNG8_STREAM
or PNG8_URL
) formats only. When its value is TRUE
, MapViewer makes the map background color completely transparent. The default value is FALSE
.
title
is an optional attribute that specifies the map title to be displayed on the top of the resulting map image.
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.
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.
The <bounding_themes>
element has the following definition:
<!ELEMENT bounding_themes (#PCDATA) > <!ATTLIST bounding_themes border_margin CDATA #IMPLIED preserve_aspect_ratio CDATA "TRUE" >
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.
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 Definition 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.
The <box>
element has the following definition:
<!ELEMENT box (coordinates) > <!ATTLIST box ID CDATA #IMPLIED srsName CDATA #REQUIRED >
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.
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.
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.14). 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.)
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>
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 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
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 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.6.
The <jdbc_image_query>
element, which is used to define an image theme (described in Section 2.3.5), 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-13 in Section 2.3.5.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.
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 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" >
For detailed usage and reference information about network themes, see Section 2.3.7.
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 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.
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.
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.8.
The <legend>
element has the following definition:
<!ELEMENT legend column+ > <!ATTLIST legend bgstyle CDATA #implied font 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 >
<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. 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-6 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.
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.
The following example shows the <legend>
element specification for the legend in Figure 2-6 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 profile
attribute (which has a default value of MEDIUM
) 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.
The <style>
element has the following definition:
<!ELEMENT style (svg | AdvancedStyle)?> <!ATTLIST theme 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>
The <styles>
element has the following definition:
<!ELEMENT styles (style+) >
The <styles>
element specifies one or more <style>
elements (described in Section 3.2.12).
The <theme>
element has the following definition:
<!ELEMENT theme (jdbc_query | jdbc_image_query | jdbc_georaster_query | jdbc_network_query | jdbc_topology_query )? > <!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" onclick CDATA #IMPLIED workspace_name CDATA #IMPLIED workspace_savepoint CDATA #IMPLIED workspace_date CDATA #IMPLIED workspace_date_format 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.6), <jdbc_network_query>
(described in Section 2.3.7), or <jdbc_topology_query>
(described in Section 2.3.8).
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.8.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.
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
.)
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.8. 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.
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.
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.7.
The <themes>
element has the following definition:
<!ELEMENT themes (theme+) >
The <themes>
element specifies one or more <theme>
elements (described in Section 3.2.14). 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.
In addition to issuing map requests (see Section 3.2) and administrative requests (see Chapter 6), 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-13 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-13 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-13 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>
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, 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.
Example 3-14 shows a map response.
Example 3-14 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> <WMTException version="1.0.0" error_code="SUCCESS"> </WMTException> </map_image> </map_response>
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.
MapViewer supports the Geometry DTD as defined in the Open GIS Consortium (OGC) GML v1.0 specification. This specification and other, more recent, versions are available at the following URL:
http://www.opengis.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)>